# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

## Tech Stack

- **Backend**: Go (embed.FS for SPA, REST API under `/api/`)
- **Frontend**: React + Vite + TypeScript + Tailwind CSS + shadcn/ui (uses **bun** as package manager)
- **Database**: PostgreSQL 16 with SQL migrations
- **Auth**: Local (bcrypt) + OIDC
- **Deployment**: Single Docker image via multi-stage build + `compose.yml`

## Project Layout

```
backend/
  cmd/server/         # Go entrypoint, embeds frontend build
  internal/
    api/              # HTTP handlers and routing
    auth/             # Local auth + OIDC logic
    db/               # Database queries and connection
    models/           # Domain types
  migrations/         # SQL migration files (sequential numbering)
frontend/
  src/
    components/       # shadcn/ui-based components
    pages/            # Route-level views
    hooks/            # Custom React hooks
    lib/              # API client, utilities
    i18n/             # Translation files (de.json, en.json)
```

## Common Commands

### Backend
```bash
cd backend && go run ./cmd/server        # Run dev server
cd backend && go test ./...              # Run all Go tests
cd backend && go test ./internal/api/... # Run tests for a specific package
cd backend && go vet ./...               # Lint
```

### Frontend
```bash
cd frontend && bun install               # Install dependencies
cd frontend && bun run dev               # Vite dev server
cd frontend && bun run build             # Production build
cd frontend && bun vitest                # Run all tests
cd frontend && bun vitest src/components/SomeComponent.test.tsx  # Single test
cd frontend && bun playwright test       # E2E tests
```

### Docker
```bash
docker compose up --build                # Full stack with PostgreSQL
docker compose up db                     # PostgreSQL only (for local dev)
```

## Architecture Notes

- The Go binary embeds the frontend build (`frontend/dist`) using `embed.FS`. All non-`/api/` routes serve the SPA for client-side routing.
- REST API lives under `/api/`. All endpoints require auth except `/api/auth/*`.
- Budget totals (available amount, budget vs actual) are computed server-side, not stored.
- Categories belong to a user and are reused across monthly budget periods. BudgetItems link a category to a specific budget with budgeted/actual amounts.
- i18n: German (de) and English (en). User preference stored in DB. Frontend uses translation files; backend returns localized error messages.
- UI uses shadcn/ui with a custom pastel color palette defined via CSS variables in the Tailwind config. Color tokens are centralized to support future theming.