SimpleFinanceDash/.planning/codebase/STACK.md

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