SimpleFinanceDash/CLAUDE.md

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

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

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

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.