# Codebase Structure

## Directory Layout

```
SimpleFinanceDash/
├── backend/                          # Go backend application
│   ├── cmd/server/                   # Application entrypoint
│   │   └── main.go                   # Server init, embeds frontend & migrations
│   ├── internal/
│   │   ├── api/                      # HTTP handlers and routing
│   │   │   ├── router.go             # Chi router setup, route definitions
│   │   │   └── handlers.go           # All HTTP request handlers (~480 lines)
│   │   ├── auth/                     # Authentication logic
│   │   │   └── auth.go               # JWT/session, bcrypt hashing
│   │   ├── db/                       # Database layer
│   │   │   ├── db.go                 # Connection pool, migration runner
│   │   │   └── queries.go            # All database queries (~350 lines, 22 functions)
│   │   └── models/                   # Domain types
│   │       └── models.go             # User, Category, Budget, BudgetItem, BudgetTotals
│   ├── migrations/                   # SQL migration files
│   │   └── 001_initial.sql           # Initial schema (5 tables, indexes, enums)
│   ├── go.mod                        # Go module (v1.25.0)
│   └── go.sum                        # Dependency lockfile
│
├── frontend/                         # React + Vite + TypeScript
│   ├── src/
│   │   ├── App.tsx                   # Root component with routing
│   │   ├── main.tsx                  # React 19 entry point
│   │   ├── index.css                 # Global styles, Tailwind + CSS variables
│   │   ├── components/               # UI and feature components
│   │   │   ├── ui/                   # shadcn/ui components (18 files)
│   │   │   │   ├── button.tsx, card.tsx, dialog.tsx, input.tsx
│   │   │   │   ├── select.tsx, table.tsx, tabs.tsx, sidebar.tsx
│   │   │   │   ├── avatar.tsx, badge.tsx, chart.tsx, separator.tsx
│   │   │   │   ├── dropdown-menu.tsx, scroll-area.tsx, sheet.tsx
│   │   │   │   ├── skeleton.tsx, spinner.tsx, tooltip.tsx
│   │   │   └── [Feature components]
│   │   │       ├── AppLayout.tsx      # Main layout wrapper
│   │   │       ├── BudgetSetup.tsx    # Budget creation form
│   │   │       ├── BillsTracker.tsx   # Bills tracking
│   │   │       ├── VariableExpenses.tsx
│   │   │       ├── DebtTracker.tsx
│   │   │       ├── FinancialOverview.tsx
│   │   │       ├── ExpenseBreakdown.tsx
│   │   │       └── AvailableBalance.tsx
│   │   ├── pages/                    # Route-level views
│   │   │   ├── DashboardPage.tsx     # Main dashboard
│   │   │   ├── CategoriesPage.tsx    # Category management
│   │   │   ├── LoginPage.tsx         # Login form
│   │   │   ├── RegisterPage.tsx      # Registration form
│   │   │   └── SettingsPage.tsx      # User settings
│   │   ├── hooks/                    # Custom React hooks
│   │   │   ├── useAuth.ts           # Auth state management
│   │   │   ├── useBudgets.ts        # Budget data fetching & selection
│   │   │   └── use-mobile.ts        # Mobile detection
│   │   ├── lib/                      # Utilities and API client
│   │   │   ├── api.ts               # Typed REST client
│   │   │   ├── utils.ts             # cn() className utility
│   │   │   └── format.ts            # Currency formatting
│   │   └── i18n/                     # Internationalization
│   │       ├── index.ts             # i18next setup
│   │       ├── en.json              # English translations
│   │       └── de.json              # German translations
│   ├── package.json                  # Dependencies (bun)
│   ├── vite.config.ts                # Build config + API proxy
│   ├── tsconfig.json                 # TypeScript config
│   ├── eslint.config.js              # ESLint config
│   ├── components.json               # shadcn/ui config
│   └── bun.lock                      # Bun lockfile
│
├── compose.yml                       # Docker Compose (PostgreSQL + app)
├── Dockerfile                        # Multi-stage build
├── CLAUDE.md                         # Project guidance
├── PRD.md                            # Product Requirements Document
└── README.md                         # Project overview
```

## Key File Locations

| Component | Location | Purpose |
|-----------|----------|---------|
| Server Entrypoint | `backend/cmd/server/main.go` | DB pool init, migrations, embed frontend |
| API Routes | `backend/internal/api/router.go` | Chi router, middleware, route definitions |
| HTTP Handlers | `backend/internal/api/handlers.go` | Auth, categories, budgets, settings handlers |
| Database Layer | `backend/internal/db/db.go` | Connection pool, migration runner |
| Queries | `backend/internal/db/queries.go` | 22 database functions using pgx |
| Models | `backend/internal/models/models.go` | User, Category, Budget, BudgetItem, BudgetTotals |
| Auth | `backend/internal/auth/auth.go` | JWT generation/validation, bcrypt |
| Migrations | `backend/migrations/001_initial.sql` | PostgreSQL schema |
| Frontend Root | `frontend/src/App.tsx` | React router, auth check, page routes |
| API Client | `frontend/src/lib/api.ts` | Typed REST client |
| i18n | `frontend/src/i18n/index.ts` | i18next setup (en, de) |
| Styling | `frontend/src/index.css` | Tailwind + CSS variables (dark/light) |

## Naming Conventions

### Backend (Go)

- **Packages**: lowercase, single word (`api`, `auth`, `db`, `models`)
- **Exported functions**: PascalCase (`GetBudget`, `CreateUser`)
- **Private functions**: camelCase
- **Constants**: PascalCase (`CategoryBill`, `userIDKey`)
- **Files**: snake_case (`handlers.go`, `router.go`, `queries.go`)
- **Types**: PascalCase (`User`, `BudgetItem`)

### Frontend (TypeScript/React)

- **Components**: PascalCase (`DashboardPage.tsx`, `BudgetSetup.tsx`)
- **Pages**: PascalCase with "Page" suffix (`LoginPage.tsx`, `CategoriesPage.tsx`)
- **Hooks**: camelCase with "use" prefix (`useAuth.ts`, `useBudgets.ts`)
- **Utilities**: camelCase (`utils.ts`, `format.ts`)
- **UI components**: kebab-case matching shadcn convention (`button.tsx`, `dropdown-menu.tsx`)
- **i18n keys**: nested dot notation (`auth.login`, `dashboard.financialOverview`)

## Configuration Files

| File | Purpose |
|------|---------|
| `backend/go.mod` | Go 1.25.0, 6 main dependencies |
| `frontend/package.json` | Node deps, bun package manager |
| `frontend/vite.config.ts` | Vite build, React plugin, API proxy to :8080 |
| `frontend/tsconfig.json` | Path alias: `@/*` → `./src/*` |
| `frontend/components.json` | shadcn/ui config (radix-nova, Lucide icons) |
| `frontend/eslint.config.js` | TypeScript + React hooks rules |
| `compose.yml` | PostgreSQL 16 + Go app services |
| `Dockerfile` | Multi-stage: bun → Go → Alpine |