# manan145/financius architecture

> Architecture diagram of the GitHub repository manan145/financius, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manan145/financius
- Repository: https://github.com/manan145/financius

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js and React, using Prisma + PostgreSQL for persistence, Clerk for authentication, Inngest for background jobs, Arcjet for request protection, and external AI (Gemini API) and email (Resend) services.
- The app consolidates account and transaction data, provides budgeting tools, AI-driven receipt scanning and coaching, and real-time alerts.

##### Main Architectural Components
a. Client (Browser)
- Next.js App Router pages and React components under `app/` and `components/`
- UI library: Tailwind CSS + shadcn/ui + Recharts for charts
- Sign-in / Sign-up flows via Clerk’s front-end SDK
b. Server (Next.js Node Runtime)
- Server Actions in `actions/` for data mutations and reads
- API Routes in `app/api/` for coach-chat, receipt scanning, seeding, background triggers
- Middleware (`middleware.js`) integrating Arcjet for request protection
- Background job handlers (Inngest functions) in `lib/inngest/` and invoked by API or scheduled events
c. Data Access Layer
- Prisma ORM (`prisma/schema.prisma`, migrations)
- Shared client in `lib/prisma.js`
d. Persistence
- PostgreSQL database, accessed via Prisma
e. Authentication & Authorization
- Clerk as the identity provider (SSR and client-side tokens)
f. External Services
- Gemini API for AI features (coach, receipt OCR)
- Resend API for email alerts
- Inngest for durable background job scheduling and execution
- Arcjet for malicious request protection

##### Relationships and Data Flows
- User → Next.js Frontend: UI rendering, form inputs, navigations
- Frontend → Server Actions / API Routes: fetch or mutate data (accounts, transactions, budgets, alerts, AI requests)
- Server → Prisma → PostgreSQL: CRUD operations on Users, Accounts, Transactions, Budgets, AlertSettings
- Server → External AI / Email APIs:
- Send receipt image to Gemini OCR endpoint
- Send user chat context to Gemini chat endpoint
- Send alert emails via Resend
- Server → Inngest: enqueue or trigger background jobs (e.g., recurring transactions, scheduled budgets alert)
- Inngest Worker → Prisma / External APIs: process jobs asynchronously

##### Architectural Patterns and Principles
- Layered Architecture: UI Layer (Next.js pages/components), Business Logic Layer (server actions, API routes), Data Layer (Prisma), Infrastructure Layer (DB, external services)
- Component-Driven UI: reusable UI primitives under `components/ui/` and domain widgets in dashboard/account/transaction folders
- Server-Side Rendering & Server Actions: fetch data close to UI for performance and security
- Progressive Disclosure: advanced settings available via on-demand UI components
- Background Processing: Inngest decouples long-running jobs from request/response cycle

##### Final Checklist
- All major components (UI, Server Actions, API Routes, DB, Background Jobs, External Services) included
- Clear separation of sync vs. async flows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User Browser"]:::user

    %% Frontend Layer
    subgraph "Next.js Frontend (UI Layer)"
        subgraph "(auth)"
            AuthLayout["layout.js"]:::frontend
            SignIn["sign-in/page.jsx"]:::frontend
            SignUp["sign-up/page.jsx"]:::frontend
        end
        subgraph "(main)"
            MainLayout["layout.js"]:::frontend
            Dashboard["dashboard/page.jsx"]:::frontend
            DashboardComp["dashboard/_components"]:::frontend
            AccountPage["account/[id]/page.jsx"]:::frontend
            AccountComp["account/_components"]:::frontend
            TransactionPage["transaction/create/page.jsx"]:::frontend
            TransactionComp["transaction/_components"]:::frontend
        end
        UIPrimitives["components/ui"]:::frontend
    end

    %% Middleware
    Middleware["middleware.js\n(lib/arcjet.js)"]:::middleware

    %% Server/API Layer
    subgraph "Business Logic Layer"
        subgraph "Server Actions"
            AccountAction["actions/account.js"]:::service
            TransactionAction["actions/transaction.js"]:::service
            BudgetAction["actions/budget.js"]:::service
            AlertAction["actions/alert-settings.js"]:::service
            DashboardAction["actions/dashboard.js"]:::service
            SeedAction["actions/seed.js"]:::service
            EmailAction["actions/send-email.js"]:::service
        end
        subgraph "API Routes"
            CoachChat["app/api/coach-chat/route.js"]:::api
            InngestAPI["app/api/inngest/route.js"]:::api
            SeedAPI["app/api/seed/route.js"]:::api
        end
    end

    %% Background Jobs
    subgraph "Inngest Background"
        InngestClient["lib/inngest/client.js"]:::background
        InngestFunc["lib/inngest/function.js"]:::background
        InngestService["Inngest\nJob Scheduling"]:::external
    end

    %% Data Access Layer
    subgraph "Data Layer"
        PrismaClient["lib/prisma.js"]:::dal
        Schema["prisma/schema.prisma"]:::dal
        Migrations["prisma/migrations"]:::dal
    end

    %% Utilities & Config
    CheckUser["lib/checkUser.js"]:::util
    Utils["lib/utils.js"]:::util
    UseFetch["hooks/use-fetch.js"]:::util
    GlobalsCSS["app/globals.css"]:::config
    TailwindCfg["tailwind.config.js"]:::config
    NextConfig["next.config.mjs"]:::config

    %% Persistence
    Postgres["PostgreSQL"]:::db

    %% External Services
    subgraph "External Services"
        Clerk["Clerk\nAuth"]:::external
        Gemini["Gemini API\nOCR & Chat"]:::external
        Resend["Resend\nEmail"]:::external
    end

    %% Flows
    User -->|"Interacts"| UIPrimitives
    UIPrimitives -->|"Renders UI"| AuthLayout
    UIPrimitives --> MainLayout
    AuthLayout --> SignIn
    AuthLayout --> SignUp
    MainLayout --> Dashboard
    MainLayout --> AccountPage
    MainLayout --> TransactionPage

    UIPrimitives -->|"Calls"| AccountAction
    UIPrimitives --> TransactionAction
    UIPrimitives --> BudgetAction
    UIPrimitives --> AlertAction
    UIPrimitives --> DashboardAction

    UIPrimitives -->|"Fetch via API"| CoachChat
    UIPrimitives --> SeedAPI
    UIPrimitives --> InngestAPI

    CoachChat ---|"Async OCR/Chat"| Gemini
    EmailAction ---|"Send Email"| Resend
    SeedAPI --> SeedAction

    CoachChat --> AccountAction
    InngestAPI --> InngestClient
    InngestClient --> InngestFunc
    InngestFunc ---|"Async Job"| Postgres
    InngestFunc ---|"Async API"| Gemini

    AccountAction --> PrismaClient
    TransactionAction --> PrismaClient
    BudgetAction --> PrismaClient
    AlertAction --> PrismaClient
    DashboardAction --> PrismaClient
    SeedAction --> PrismaClient

    PrismaClient -->|"Executes"| Schema
    Schema -->|"Migrates"| Migrations
    PrismaClient -->|"SQL Queries"| Postgres

    Middleware -->|"Protects"| AuthLayout
    Middleware -->|"Protects"| MainLayout
    Middleware --> Clerk

    CheckUser -.-> AuthLayout
    CheckUser -.-> MainLayout

    %% Click Events
    click AuthLayout "https://github.com/manan145/financius/blob/main/app/(auth)/layout.js"
    click SignIn "https://github.com/manan145/financius/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.jsx"
    click SignUp "https://github.com/manan145/financius/blob/main/app/(auth)/sign-up/[[...sign-up]]/page.jsx"
    click MainLayout "https://github.com/manan145/financius/blob/main/app/(main)/layout.js"
    click Dashboard "https://github.com/manan145/financius/blob/main/app/(main)/dashboard/page.jsx"
    click DashboardComp "https://github.com/manan145/financius/tree/main/app/(main)/dashboard/_components/"
    click AccountPage "https://github.com/manan145/financius/blob/main/app/(main)/account/[id]/page.jsx"
    click AccountComp "https://github.com/manan145/financius/tree/main/app/(main)/account/_components/"
    click TransactionPage "https://github.com/manan145/financius/blob/main/app/(main)/transaction/create/page.jsx"
    click TransactionComp "https://github.com/manan145/financius/tree/main/app/(main)/transaction/_components/"
    click UIPrimitives "https://github.com/manan145/financius/tree/main/components/ui/"
    click AccountAction "https://github.com/manan145/financius/blob/main/actions/account.js"
    click TransactionAction "https://github.com/manan145/financius/blob/main/actions/transaction.js"
    click BudgetAction "https://github.com/manan145/financius/blob/main/actions/budget.js"
    click AlertAction "https://github.com/manan145/financius/blob/main/actions/alert-settings.js"
    click DashboardAction "https://github.com/manan145/financius/blob/main/actions/dashboard.js"
    click SeedAction "https://github.com/manan145/financius/blob/main/actions/seed.js"
    click EmailAction "https://github.com/manan145/financius/blob/main/actions/send-email.js"
    click CoachChat "https://github.com/manan145/financius/blob/main/app/api/coach-chat/route.js"
    click InngestAPI "https://github.com/manan145/financius/blob/main/app/api/inngest/route.js"
    click SeedAPI "https://github.com/manan145/financius/blob/main/app/api/seed/route.js"
    click Middleware "https://github.com/manan145/financius/blob/main/middleware.js"
    click PrismaClient "https://github.com/manan145/financius/blob/main/lib/prisma.js"
    click Schema "https://github.com/manan145/financius/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/manan145/financius/tree/main/prisma/migrations/"
    click CheckUser "https://github.com/manan145/financius/blob/main/lib/checkUser.js"
    click Utils "https://github.com/manan145/financius/blob/main/lib/utils.js"
    click UseFetch "https://github.com/manan145/financius/blob/main/hooks/use-fetch.js"
    click GlobalsCSS "https://github.com/manan145/financius/blob/main/app/globals.css"
    click TailwindCfg "https://github.com/manan145/financius/blob/main/tailwind.config.js"
    click NextConfig "https://github.com/manan145/financius/blob/main/next.config.mjs"
    click InngestClient "https://github.com/manan145/financius/blob/main/lib/inngest/client.js"
    click InngestFunc "https://github.com/manan145/financius/blob/main/lib/inngest/function.js"

    %% Styles
    classDef user fill:#e0f7fa,stroke:#006064,color:#006064
    classDef frontend fill:#e3f2fd,stroke:#1976d2,color:#0d47a1
    classDef middleware fill:#eceff1,stroke:#455a64,color:#263238
    classDef service fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef api fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef background fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
    classDef dal fill:#fff3e0,stroke:#fb8c00,color:#e65100
    classDef db fill:#ffe0b2,stroke:#ff6f00,color:#e65100
    classDef external fill:#fce4ec,stroke:#d81b60,color:#880e4f
    classDef util fill:#f5f5f5,stroke:#9e9e9e,color:#616161
    classDef config fill:#fafafa,stroke:#cfd8dc,color:#37474f
```
