docs: map existing codebase

2026-03-16 11:19:29 +01:00
parent 65d9842831
commit 45e0f779a4
7 changed files with 1609 additions and 0 deletions
--- a/.planning/codebase/STRUCTURE.md
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,249 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-03-16
+
+## Directory Layout
+
+```
+SimpleFinanceDash/
+├── src/                          # All application source code
+│   ├── main.tsx                  # React 19 app entry point with providers
+│   ├── App.tsx                   # Route configuration and guards
+│   ├── index.css                 # Global Tailwind styles
+│   ├── pages/                    # Page components (routed views)
+│   ├── components/               # Reusable and layout components
+│   │   └── ui/                   # Shadcn/Radix UI primitives (16 components)
+│   ├── hooks/                    # Custom data-fetching hooks (TanStack Query)
+│   ├── lib/                      # Utilities, types, configuration
+│   └── i18n/                     # Internationalization setup and resources
+├── supabase/                     # Supabase project files
+│   └── migrations/               # Database schema migrations
+├── public/                       # Static assets
+├── index.html                    # HTML entry point for Vite
+├── package.json                  # Dependencies and build scripts
+├── vite.config.ts                # Vite bundler configuration
+├── tsconfig.json                 # TypeScript base configuration
+├── tsconfig.app.json             # App-specific TypeScript config
+├── tsconfig.node.json            # Build script TypeScript config
+├── eslint.config.js              # ESLint configuration
+├── components.json               # Shadcn CLI component registry
+├── .env.example                  # Example environment variables template
+└── .gitignore                    # Git ignore rules
+
+```
+
+## Directory Purposes
+
+**`src/pages/`:**
+- Purpose: Page-level components that correspond to routes in App.tsx
+- Contains: 9 page components (all .tsx)
+- Key files:
+  - `DashboardPage.tsx` (316 lines) - Monthly budget dashboard with charts
+  - `BudgetDetailPage.tsx` (555 lines) - Detailed budget editing and item management
+  - `TemplatePage.tsx` (459 lines) - Monthly budget template editor
+  - `BudgetListPage.tsx` (261 lines) - List of all budgets with quick actions
+  - `CategoriesPage.tsx` (214 lines) - Category management (CRUD)
+  - `QuickAddPage.tsx` (202 lines) - Quick-add library editor
+  - `SettingsPage.tsx` (125 lines) - User preferences
+  - `LoginPage.tsx` (107 lines) - Email/password and OAuth login
+  - `RegisterPage.tsx` (81 lines) - User registration form
+
+Each page follows pattern:
+- Imports hooks at top
+- Calls hooks in component body
+- Renders UI from state
+- Delegates complex logic to sub-components
+
+**`src/components/`:**
+- Purpose: Reusable UI components and layout wrappers
+- Contains: Custom components + UI library primitives
+- Key files:
+  - `AppLayout.tsx` - Sidebar wrapper for authenticated pages
+  - `QuickAddPicker.tsx` - Multi-modal quick-add workflow component
+  - `ui/` - 16 Shadcn-based components (Button, Dialog, Select, Table, etc.)
+
+**`src/hooks/`:**
+- Purpose: Encapsulate all server communication and state queries
+- Contains: 6 custom hooks
+- Key files:
+  - `useAuth.ts` - Session management and auth operations (signUp, signIn, signOut)
+  - `useBudgets.ts` - Budget CRUD, item management, template generation
+  - `useCategories.ts` - Category CRUD operations
+  - `useTemplate.ts` - Monthly budget template management
+  - `useQuickAdd.ts` - Quick-add item library CRUD
+  - `use-mobile.ts` - Responsive breakpoint detection utility
+
+Each hook:
+- Defines typed query keys as const arrays
+- Initializes useQuery/useMutation from TanStack Query
+- Returns { data, loading, ...mutations }
+- Implements onSuccess cache invalidation
+
+**`src/lib/`:**
+- Purpose: Core utilities, types, and configuration
+- Contains: 5 files
+- Key files:
+  - `types.ts` - TypeScript interfaces: Profile, Category, Budget, BudgetItem, Template, TemplateItem, QuickAddItem
+  - `supabase.ts` - Supabase client creation with environment validation
+  - `palette.ts` - Category color constants (CSS variables) and labels (en/de)
+  - `format.ts` - Currency formatting with Intl.NumberFormat API
+  - `utils.ts` - General helpers (like cn for class merging)
+
+**`src/i18n/`:**
+- Purpose: Internationalization setup and resource files
+- Contains: `index.ts` and JSON translation files
+- Key files:
+  - `index.ts` - i18next initialization with react-i18next bindings
+  - `en.json` - English translation strings (namespaced by feature)
+  - `de.json` - German translation strings
+- Initialized at app startup before any React render
+- Provides `useTranslation()` hook for all components
+
+**`src/components/ui/`:**
+- Purpose: Unstyled, accessible UI primitives from Shadcn and Radix UI
+- Contains: 16 files of component exports
+- Includes: Badge, Button, Card, Dialog, Dropdown Menu, Input, Label, Popover, Select, Separator, Sheet, Sidebar, Skeleton, Table, Tooltip, Sonner Toast wrapper
+- Pattern: Each wraps Radix primitive with Tailwind styling
+- Do NOT modify these files — regenerate via Shadcn CLI if needed
+
+## Key File Locations
+
+**Entry Points:**
+- `src/main.tsx` - DOM mount point, providers initialization
+- `src/App.tsx` - Route definitions and authentication guards
+- `index.html` - Vite HTML template with root div
+
+**Configuration:**
+- `vite.config.ts` - Build tooling (React plugin, Tailwind vite plugin, @ alias)
+- `tsconfig.json` - Base TS config with @ path alias
+- `eslint.config.js` - Linting rules
+- `components.json` - Shadcn CLI registry
+- `package.json` - Dependencies: react@19, react-router-dom@7, @tanstack/react-query@5, @supabase/supabase-js@2, i18next, lucide-react, recharts, tailwindcss@4, sonner
+
+**Core Logic:**
+- `src/hooks/useBudgets.ts` - Largest hook (369 lines) with factory pattern for detail queries
+- `src/hooks/useTemplate.ts` - Template mutations with sort_order management
+- `src/lib/types.ts` - Single source of truth for domain types
+- `src/lib/supabase.ts` - Client configuration (2 lines of config + validation)
+
+**Testing:**
+- No test files present (no `*.test.ts`, `*.spec.ts`)
+- No jest.config.js or vitest.config.ts
+
+## Naming Conventions
+
+**Files:**
+- Pages: PascalCase with "Page" suffix (`DashboardPage.tsx`)
+- Hooks: camelCase with "use" prefix (`useAuth.ts`, `useBudgets.ts`)
+- Components: PascalCase (`AppLayout.tsx`, `QuickAddPicker.tsx`)
+- Utilities: camelCase descriptive (`format.ts`, `palette.ts`)
+- Types: camelCase file, PascalCase exports (`types.ts` exports `interface Budget`)
+- UI components: kebab-case file, PascalCase export (`card.tsx` exports `Card`)
+
+**Directories:**
+- Feature folders: lowercase plural (`src/hooks/`, `src/pages/`, `src/components/`)
+- UI library: `ui/` subfolder under components
+
+**Functions & Variables:**
+- Functions: camelCase (`formatCurrency`, `useBudgets`)
+- Component functions: PascalCase (`DashboardPage`, `QuickAddPicker`)
+- Constants: UPPER_SNAKE_CASE (`CATEGORY_TYPES`, `EXPENSE_TYPES`)
+- Variables: camelCase (`budgetId`, `categoryId`, `isSaving`)
+
+**Types:**
+- Interfaces: PascalCase (`Budget`, `BudgetItem`)
+- Type unions: PascalCase (`CategoryType`)
+- Props interfaces: PascalCase ending with "Props" (`QuickAddPickerProps`)
+
+## Where to Add New Code
+
+**New Feature (e.g., Reports):**
+1. Create page: `src/pages/ReportsPage.tsx`
+2. Create hook: `src/hooks/useReports.ts` with query keys and mutations
+3. Add types: `src/lib/types.ts` - add new interfaces (Report, ReportItem)
+4. Add route: `src/App.tsx` - add Route element
+5. Add nav link: `src/components/AppLayout.tsx` - add to navItems array
+6. Add i18n: `src/i18n/en.json` and `src/i18n/de.json` - add new keys
+
+**New Component (e.g., CategoryBadge):**
+- If simple display component: `src/components/CategoryBadge.tsx`
+- If UI primitive wrapper: `src/components/ui/category-badge.tsx` (follow shadcn pattern)
+- Composition: Import from ui/ folder, layer styling via className
+
+**New Utility Function:**
+- General helpers: `src/lib/utils.ts`
+- Domain-specific (e.g., budget math): Add to relevant hook file or create `src/lib/budgetHelpers.ts`
+- Formatting logic: `src/lib/format.ts`
+
+**New Hook:**
+- Data fetching: `src/hooks/useFeatureName.ts`
+- Pattern: Export named function, define query keys, use useQuery/useMutation, return typed object
+- Example structure from `useTemplate.ts`:
+  - Query keys at top (const)
+  - Helper functions (async functions)
+  - Main hook function with useQuery/useMutation setup
+  - Exposed API object return
+
+**Styling:**
+- Component styles: Tailwind className in JSX (no CSS files)
+- Global styles: `src/index.css` (imports Tailwind directives)
+- Color system: CSS variables in theme (Tailwind config)
+- Category colors: `src/lib/palette.ts` (maps to CSS var(--color-X))
+
+## Special Directories
+
+**`src/components/ui/`:**
+- Purpose: Shadcn registry of unstyled, accessible Radix UI components
+- Generated: Via `npx shadcn-ui@latest add [component]`
+- Committed: Yes (production code)
+- Do NOT hand-edit — regenerate if Shadcn updates
+
+**`public/`:**
+- Purpose: Static assets (favicon, images, fonts)
+- Generated: No
+- Committed: Yes
+- Served at root by Vite
+
+**`supabase/migrations/`:**
+- Purpose: Database schema as versioned SQL files
+- Generated: Via Supabase CLI
+- Committed: Yes (tracked via git)
+- Applied: By `supabase db push` command
+
+**`.env` files:**
+- Purpose: Runtime configuration (Supabase URL, API key)
+- Generated: Via `.env.example` template
+- Committed: NO — in .gitignore
+- Required for: Local dev and CI/CD
+
+**`dist/`:**
+- Purpose: Production bundle output
+- Generated: Via `npm run build`
+- Committed: No — in .gitignore
+- Deployment: Upload contents to CDN or web server
+
+## Code Organization Principles
+
+**Vertical Slices:**
+- Feature → Page → Hook → Library
+- Minimizes cross-feature coupling
+- Easy to add/remove features
+
+**Co-location of Related Code:**
+- Page component near its hooks
+- Query keys defined in same hook as queries
+- Mutations and queries in same hook for domain entity
+
+**Type Safety:**
+- All Supabase queries cast return value to TypeScript type
+- TanStack Query generic parameters: `useQuery<Type>()` and `useMutation<Payload, Response>()`
+- Props interfaces for all custom components
+
+**Consistent Hook Patterns:**
+- All data hooks follow: query setup → mutations setup → return typed object
+- Mutations always have onSuccess cache invalidation
+- Query keys are hierarchical arrays enabling granular invalidation
+
+---
+
+*Structure analysis: 2026-03-16*