Skip to content

System Architecture

Technology Stack

  • Framework: Next.js 16 (App Router)
  • Language: TypeScript / JavaScript
  • Styling: Tailwind CSS v4
  • Database: Supabase (PostgreSQL)
  • Authentication: Supabase Auth
  • Testing: Vitest with React Testing Library

Project Structure

The project follows the Next.js App Router convention with a feature-based organization.

/
├── app/                  # Next.js App Router pages and layouts
│   ├── (auth)/           # Authentication routes (login, signup)
│   ├── api/              # API Route Handlers
│   └── dashboard/        # Protected main application area
│       ├── analysis/     # Deal Analysis feature
│       ├── bookkeeping/  # Bookkeeping feature
│       ├── projects/     # Project Management (Budget & Tasks)
│       ├── notifications/# In-app Inbox
│       └── admin/        # Admin management tools
├── components/           # Shared UI components (Buttons, Inputs, etc.)
├── features/             # Feature-specific logic (Hooks, specialized components)
│   ├── analysis/
│   ├── bookkeeping/
│   ├── projects/
│   └── collaboration/
├── hooks/                # Global custom hooks
├── lib/                  # Utilities (Supabase client, helpers)
└── types/                # TypeScript type definitions

Key Architectural Decisions

  1. Server vs. Client Components:
  2. We use Server Components for data fetching and layout structure where possible to minimize JS bundle size.

  3. Client Components are used for interactive elements (forms, calculators, dashboards) and use the 'use client' directive.

  4. State Management:

  5. URL State: For shareable and persistent state (e.g., search queries, active tabs).
  6. React Context: For global UI state (e.g., Toast notifications).

  7. React Query (via Supabase hooks): For server state management, caching, and optimistic updates.

  8. Security:

  9. Middleware: Running on the edge, this intercepts requests to /dashboard/* and verifies the user's session before they reach the page.
  10. RLS (Row Level Security): The database acts as the distinct source of truth for authorization. Even if the frontend exposes an endpoint, the database will reject queries for data the user doesn't own (unless they are an Admin).