docs: map existing codebase

.planning/codebase/STACK.md

@@ -0,0 +1,130 @@
+# Technology Stack
+
+**Analysis Date:** 2026-03-11
+
+## Languages
+
+**Primary:**
+- Go 1.25.0 - Backend REST API, SPA server, database migrations
+- TypeScript 5.9.3 - Frontend React application, type-safe client code
+- SQL - Database schema and migrations (PostgreSQL)
+
+**Secondary:**
+- HTML/CSS - Frontend markup and styling (via React/Tailwind)
+- JavaScript - Runtime for frontend (via TypeScript compilation)
+
+## Runtime
+
+**Environment:**
+- Go 1.25.0 - Backend runtime (production: Alpine-based Docker)
+- Node.js 19+ (implied via Bun) - Frontend build only
+- Bun 1.x - JavaScript package manager and runtime
+
+**Package Manager:**
+- Bun - JavaScript/TypeScript package manager
+  - Lockfile: `frontend/bun.lock` (present)
+- Go modules - Go dependency management
+  - Lockfile: `backend/go.mod`, `backend/go.sum` (present)
+
+## Frameworks
+
+**Core:**
+- React 19.2.0 - Frontend UI framework
+- Chi v5.2.5 - Go HTTP router with middleware support
+- Vite 7.3.1 - Frontend build tool and dev server
+
+**UI/Styling:**
+- Tailwind CSS 4.2.1 - Utility-first CSS framework with Vite plugin
+- shadcn/ui 4.0.0 - Component library built on Radix UI
+- Radix UI 1.4.3 - Headless UI component primitives
+
+**Charting/Data Visualization:**
+- Recharts 2.15.4 - React charting library for budget visualization
+
+**Internationalization:**
+- i18next 25.8.14 - Frontend i18n framework
+- react-i18next 16.5.6 - React bindings for i18next
+
+**Routing:**
+- React Router DOM 7.13.1 - Frontend client-side routing
+
+## Key Dependencies
+
+**Critical:**
+- jackc/pgx/v5 v5.8.0 - PostgreSQL driver and connection pooling (pgxpool)
+- golang-jwt/jwt/v5 v5.3.1 - JWT token generation and validation for session auth
+- golang.org/x/crypto v0.48.0 - bcrypt password hashing
+
+**Infrastructure:**
+- chi/v5 v5.2.5 - HTTP router with CORS and compression middleware
+- chi/cors v1.2.2 - CORS middleware for Go
+- google/uuid v1.6.0 - UUID generation for database IDs
+- shopspring/decimal v1.4.0 - Precise decimal arithmetic for currency amounts
+- tailwindcss/vite v4.2.1 - Tailwind CSS Vite integration
+
+**Frontend Utilities:**
+- clsx 2.1.1 - Conditional className utility
+- tailwind-merge 3.5.0 - Merge and deduplicate Tailwind CSS classes
+- class-variance-authority 0.7.1 - Type-safe component variant system
+- lucide-react 0.577.0 - Icon library for React
+- @fontsource-variable/geist 5.2.8 - Geist variable font
+
+**Dev Tools:**
+- TypeScript ESLint 8.48.0 - Linting for TypeScript/JavaScript
+- ESLint 9.39.1 - Base linting framework
+- @vitejs/plugin-react 5.1.1 - Vite plugin for React (JSX/Fast Refresh)
+
+## Configuration
+
+**Environment:**
+- Configuration via environment variables:
+  - `DATABASE_URL` - PostgreSQL connection string (default: `postgres://simplefin:simplefin@localhost:5432/simplefindb?sslmode=disable`)
+  - `SESSION_SECRET` - Secret for JWT signing (default: `change-me-in-production`)
+  - `PORT` - Server port (default: `8080`)
+  - `OIDC_ISSUER` - OIDC provider issuer URL (optional)
+  - `OIDC_CLIENT_ID` - OIDC client identifier (optional)
+  - `OIDC_CLIENT_SECRET` - OIDC client secret (optional)
+- Env file: Not detected - uses environment variables at runtime
+
+**Build:**
+- Frontend: `frontend/vite.config.ts` - Vite configuration with React and Tailwind plugins
+- Frontend: `frontend/tsconfig.app.json` - TypeScript compiler options (ES2022, strict mode)
+- Frontend: `frontend/tsconfig.node.json` - TypeScript config for build tools
+- Frontend: `frontend/eslint.config.js` - ESLint configuration
+- Frontend: `frontend/components.json` - shadcn/ui component configuration
+- Backend: Multi-stage Docker build via `Dockerfile` (Bun frontend → Go backend → Alpine)
+
+## Platform Requirements
+
+**Development:**
+- Docker and Docker Compose (for local PostgreSQL)
+- Go 1.25.0+
+- Bun or Node.js 19+ (frontend)
+- PostgreSQL 16 compatible (for `docker compose up db`)
+
+**Production:**
+- Alpine Linux (via Docker image from `Dockerfile`)
+- PostgreSQL 16 (external database)
+- Single Docker image deployment: embeds frontend build and migrations
+
+## Deployment
+
+**Build Strategy:**
+- Multi-stage Docker build (file: `Dockerfile`):
+  1. Stage 1 (Bun): Build frontend React app → `frontend/dist`
+  2. Stage 2 (Go): Download Go dependencies, embed frontend dist and migrations, compile binary
+  3. Stage 3 (Alpine): Minimal runtime image with single `/server` binary
+- Binary embeds:
+  - Frontend static files via `embed.FS` at `cmd/server/frontend_dist/`
+  - SQL migrations via `embed.FS` at `cmd/server/migrations/`
+
+**Compose Configuration:**
+- File: `compose.yml`
+- Services:
+  - `app`: Built from Dockerfile, exposes port 8080
+  - `db`: PostgreSQL 16 Alpine, exposes port 5432, volume: `pgdata`
+- Health checks: PostgreSQL readiness check before app startup
+
+---
+
+*Stack analysis: 2026-03-11*