SimpleFinanceDash/.planning/codebase/STRUCTURE.md

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