# juliengdev/personal_finance architecture

> Architecture diagram of the GitHub repository juliengdev/personal_finance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juliengdev/personal_finance
- Repository: https://github.com/juliengdev/personal_finance

## Overview

##### Project type and purpose
- This is a full-stack Personal Finance web application built with Next.js (app directory), React, TypeScript, and Prisma.
- The app implements authentication (NextAuth), CRUD operations on budgets, pots, transactions, and recurring bills, backed by a relational database managed via Prisma.
- It exposes API routes for auth and business-logic actions, and renders both server- and client-side React components.

##### File structure
- Top-level “app” directory: Next.js 13+ routes and React Server/Client Components.
- “app/api/auth/[...nextauth]”: NextAuth route for login/signup, backed by Prisma adapter.
- “actions”: server actions for budgets, pots, transactions, signup—invoked from client components.
- “components”: UI layer organized by feature (auth, budgets, pots, transactions, recurring-bills, overview, filters, modal, pagination, ui).
- “lib”: shared utilities (auth, constants, font loading, Prisma client, Zod schemas, file upload, business utils).
- “prisma”: schema, migrations, seed scripts—defines database tables for users, budgets, transactions, pots, bills.
- “public” & “styles”: static assets & CSS.
- “__tests__” & jest.config.ts: automated tests for services & components.

##### README for additional insights
- Describes core features: overview dashboard, paginated/searchable transactions, CRUD budgets & pots, recurring bills, accessibility, responsive layouts.
- Suggests use of data.json for initial load, and optionally persisting to database (in our case we do).
- Mentions authentication and database as bonuses—our implementation includes both.

##### Main components & relationships
a. Frontend (Client)
- React components in “app” & “components” folders, some using server actions (form submissions) and client hooks.
- Pages (e.g., /dashboard/overview, /transactions) render UI, call actions via Next.js form actions or fetch API.
b. Backend (Server)
- Next.js Server: handles page rendering, API routes, server actions.
- API/auth route: NextAuth endpoint, integrates with OAuth/providers and session management.
- Actions: functions run server-side (in “actions”) to read/write data via Prisma.
c. Database
- PostgreSQL/MySQL (configured via environment) accessed through Prisma Client (lib/prisma.ts).
- Tables: User, Budget, Transaction, Pot, RecurringBill, Session.
d. External Services
- OAuth providers for social login (GitHub, Google, etc.) via NextAuth.
- File upload service if used (lib/upload.ts).
e. Build & Deployment
- Hosted on Vercel/Netlify: Next.js app, serverless functions for API routes/actions.
- Prisma migrations & seed scripts run at deploy time to create schema & initial data.

##### Architectural patterns & design principles
- “App Router” pattern: Next.js file-based routing in “app” folder, mixing Server and Client Components.
- Server Actions: form-based mutations handled directly in component files, reducing explicit fetch code.
- MVC-lite: React UI (View), actions & API (Controller), Prisma & DB (Model).
- Modularization: feature folders under “components” and “hooks” for reusability and separation of concerns.
- Type-safe schema/validation: Zod schemas in lib/schemas.ts for request payloads.

##### Final advice
- Every distinct layer: Client, Server (App Router vs. API vs. Actions), DB, External Auth.
- Keep labels concise, group related features (budgets, pots, transactions) under the Actions/API section.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Browser" 
        direction TB
        ReactApp["Next.js App Router"]:::ui
        AuthUI["Authentication UI Components"]:::ui
        OverviewUI["Overview Components"]:::ui
        BudgetUI["Budget Components"]:::ui
        PotUI["Pot Components"]:::ui
        TransactionUI["Transaction Components"]:::ui
        RecurringUI["Recurring Bills Components"]:::ui
        Filters["Filters Components"]:::ui
        Modal["Modal Components"]:::ui
        Pagination["Pagination Components"]:::ui
        SharedUI["Shared UI Components"]:::ui
        Hooks["React Hooks"]:::ui
        Styles["Global Stylesheets"]:::ui
    end

    %% Server Layer
    subgraph "Next.js Server" 
        direction TB
        SSR["Server Components & App Router"]:::server
        AuthAPI["Authentication API Route"]:::server
        SignupAction["Signup Action"]:::server
        BudgetService["Budget Services"]:::server
        PotService["Pot Services"]:::server
        TransactionService["Transaction Services"]:::server
        BalanceService["Balance Service"]:::server
        PrismaClient["Prisma Client & Config"]:::server
        Zod["Zod Schemas"]:::server
        AuthUtil["Authentication Utilities"]:::server
        BizUtil["Business Utilities"]:::server
        FileUpload["File Upload Utility"]:::server
        Constants["Constants & Type Definitions"]:::server
        Utils["Global Utilities"]:::server
        DataAPI["Static Data for Initial Load"]:::server
        Tests["Automated Tests"]:::server
        Jest["Jest Configuration"]:::server
    end

    %% Database Layer
    subgraph "Database" 
        direction TB
        RDBMS["Relational Database"]:::db
        Schema["DB Schema & Migrations"]:::db
        Seed["Seed Script"]:::db
    end

    ExternalOAuth["OAuth Providers"]:::external

    %% Flows
    ReactApp -->|"GET page"| SSR
    AuthUI -->|"POST form action"| AuthAPI
    SSR -->|"renders pages"| ReactApp
    ReactApp -->|"fetch form actions"| SSR
    SignupAction -->|"invoke Prisma Client"| PrismaClient
    BudgetService -->|"invoke Prisma Client"| PrismaClient
    PotService -->|"invoke Prisma Client"| PrismaClient
    TransactionService -->|"invoke Prisma Client"| PrismaClient
    BalanceService -->|"invoke Prisma Client"| PrismaClient
    AuthAPI -->|"reads/writes session"| PrismaClient
    AuthAPI -->|"OAuth handshake"| ExternalOAuth
    PrismaClient -->|"DB read/write"| RDBMS
    Zod -->|"validate payload"| SignupAction
    Zod -->|"validate payload"| BudgetService
    Zod -->|"validate payload"| PotService
    Zod -->|"validate payload"| TransactionService
    Zod -->|"validate payload"| BalanceService
    DataAPI -->|"initial data load"| ReactApp
    Tests -->|"test services/UI"| SSR
    Jest -->|"configures tests"| Tests

    %% Click Events
    click ReactApp "https://github.com/juliengdev/personal_finance/tree/main/app/"
    click AuthAPI "https://github.com/juliengdev/personal_finance/blob/main/app/api/auth/[...nextauth]/route.ts"
    click AuthUI "https://github.com/juliengdev/personal_finance/tree/main/components/auth/"
    click SignupAction "https://github.com/juliengdev/personal_finance/blob/main/actions/signup.ts"
    click BudgetService "https://github.com/juliengdev/personal_finance/blob/main/actions/budgets.ts"
    click PotService "https://github.com/juliengdev/personal_finance/blob/main/actions/pots.ts"
    click TransactionService "https://github.com/juliengdev/personal_finance/blob/main/actions/transactions.ts"
    click BalanceService "https://github.com/juliengdev/personal_finance/blob/main/actions/balance.ts"
    click OverviewUI "https://github.com/juliengdev/personal_finance/tree/main/components/overview/"
    click BudgetUI "https://github.com/juliengdev/personal_finance/tree/main/components/budgets/"
    click PotUI "https://github.com/juliengdev/personal_finance/tree/main/components/pots/"
    click TransactionUI "https://github.com/juliengdev/personal_finance/tree/main/components/transactions/"
    click RecurringUI "https://github.com/juliengdev/personal_finance/tree/main/components/recurring/"
    click Filters "https://github.com/juliengdev/personal_finance/tree/main/components/filters/"
    click Modal "https://github.com/juliengdev/personal_finance/tree/main/components/modal/"
    click Pagination "https://github.com/juliengdev/personal_finance/tree/main/components/pagination/"
    click SharedUI "https://github.com/juliengdev/personal_finance/tree/main/components/ui/"
    click Hooks "https://github.com/juliengdev/personal_finance/tree/main/hooks/"
    click Styles "https://github.com/juliengdev/personal_finance/blob/main/styles/globals.css"
    click PrismaClient "https://github.com/juliengdev/personal_finance/blob/main/lib/prisma.ts"
    click Zod "https://github.com/juliengdev/personal_finance/blob/main/lib/schemas.ts"
    click AuthUtil "https://github.com/juliengdev/personal_finance/blob/main/lib/auth.ts"
    click BizUtil "https://github.com/juliengdev/personal_finance/blob/main/lib/utilsBudgets.ts"
    click FileUpload "https://github.com/juliengdev/personal_finance/blob/main/lib/upload.ts"
    click Constants "https://github.com/juliengdev/personal_finance/blob/main/lib/constants.ts"
    click Utils "https://github.com/juliengdev/personal_finance/blob/main/lib/utils.ts"
    click Schema "https://github.com/juliengdev/personal_finance/blob/main/prisma/schema.prisma"
    click Seed "https://github.com/juliengdev/personal_finance/blob/main/prisma/scripts/seed.ts"
    click DataAPI "https://github.com/juliengdev/personal_finance/blob/main/data/data.json"
    click Tests "https://github.com/juliengdev/personal_finance/tree/main/__tests__/"
    click Jest "https://github.com/juliengdev/personal_finance/blob/main/jest.config.ts"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef server fill:#E2F0D9,stroke:#2E7D32,color:#2E7D32
    classDef db fill:#FFE7D9,stroke:#D84315,color:#D84315
    classDef external fill:#F0F0F0,stroke:#666666,color:#666666
```
