7.2 KiB
7.2 KiB
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 |