# bhavyaalekhya/nudget architecture

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

- Interactive diagram: https://gitdiagram.com/bhavyaalekhya/nudget
- Repository: https://github.com/bhavyaalekhya/nudget

## Overview

##### Main Components
a. **Electron Shell (main.js)**
- Acts as the desktop “container.”
- Launches two child processes in development: the Next.js dev server (frontend) and the Express server (backend).
b. **Frontend – Next.js App**
- Written in React with the App Router (app/ directory).
- Renders pages, React components (charts, panels, forms).
- Fetches data via HTTP/REST from the backend API.
- Uses Chart.js for visualizations and React Context for theming.
c. **Backend – Express + Prisma ORM**
- Exposes REST routes under /category, /theme, /prediction, /transactions.
- Business logic in route handlers and utility modules (e.g., predictSpending.ts).
- Uses Prisma as an ORM to read/write the SQLite database.
d. **Database – SQLite**
- A local file-based database (schema defined in prisma/schema.prisma).
- Migrated via Prisma Migrate (migrations folder).
e. **Python Utilities (python-files/)**
- A sidecar service or scripts for advanced categorization or ML (app.py, categorize.py).
- Could be invoked by Node (child_process) or run as a separate microservice.

##### Relationships and Data Flows
- **Electron → Frontend**: Electron’s BrowserWindow loads the Next.js URL (localhost:3000 in dev or static files in prod).
- **Frontend ↔ Backend**: All data operations (CRUD on expenses/incomes, forecast requests) flow via HTTP calls (e.g., fetchPrediction.ts).
- **Backend → Database**: Prisma client executes SQL queries on the SQLite file.
- **Backend ↔ Python Utilities** (optional): For transaction categorization or ML predictions, the Express server may spawn or send HTTP/RPC requests to the Python scripts.

##### Architectural Patterns
- **Layered Architecture**:
– Presentation Layer (Next.js)
– API Layer (Express routes/controllers)
– Data Access Layer (Prisma ORM)
– Database (SQLite)
- **Separation of Concerns**: Distinct repos/directories for frontend, backend, and desktop shell.
- **Modular Components**: Next.js App Router folders correspond to pages/views; Express routes map to resource controllers.
- **Microservice-like Utility**: The Python folder can be drawn as an external service if invoked at runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Electron Shell
    Electron["Electron Main Process\n(main.js)"]:::ui
    click Electron "https://github.com/bhavyaalekhya/nudget/blob/main/main.js"

    %% DevOps / Build
    DevOps["DevOps / Build\n(package.json)"]:::devops
    click DevOps "https://github.com/bhavyaalekhya/nudget/blob/main/package.json"

    %% Frontend Layer
    subgraph "Frontend\nNext.js + React" 
        FE_APP["App Router\n(app/)"]:::ui
        FE_COMP["Components\n(components/)"]:::ui
        FE_THEME["Theme Context\n(themecontext.tsx)"]:::ui
        FE_FETCH["fetchPrediction.ts"]:::ui
        FE_NEXT["next.config.ts"]:::ui
    end
    click FE_APP "https://github.com/bhavyaalekhya/nudget/tree/main/frontend/src/app"
    click FE_COMP "https://github.com/bhavyaalekhya/nudget/tree/main/frontend/src/app/components"
    click FE_THEME "https://github.com/bhavyaalekhya/nudget/blob/main/frontend/src/app/context/themecontext.tsx"
    click FE_FETCH "https://github.com/bhavyaalekhya/nudget/blob/main/frontend/src/utils/fetchPrediction.ts"
    click FE_NEXT "https://github.com/bhavyaalekhya/nudget/blob/main/frontend/next.config.ts"

    %% Backend Layer
    subgraph "Backend\nExpress.js + Prisma" 
        BE_SERVER["server.ts"]:::api
        BE_ROUTES["Routes"]:::api
        CAT_ROUTE["category.route.ts"]:::api
        THEME_ROUTE["theme.route.ts"]:::api
        PRED_ROUTE["prediction.route.ts"]:::api
        TRANS_ROUTE["transactions.ts"]:::api
        BE_UTIL["predictSpending.ts"]:::api
        BE_PKG["package.json"]:::api
    end
    click BE_SERVER "https://github.com/bhavyaalekhya/nudget/blob/main/backend/src/server.ts"
    click CAT_ROUTE "https://github.com/bhavyaalekhya/nudget/blob/main/backend/src/routes/category.route.ts"
    click THEME_ROUTE "https://github.com/bhavyaalekhya/nudget/blob/main/backend/src/routes/theme.route.ts"
    click PRED_ROUTE "https://github.com/bhavyaalekhya/nudget/blob/main/backend/src/routes/prediction.route.ts"
    click TRANS_ROUTE "https://github.com/bhavyaalekhya/nudget/blob/main/backend/src/routes/transactions.ts"
    click BE_UTIL "https://github.com/bhavyaalekhya/nudget/blob/main/backend/src/utils/predictSpending.ts"
    click BE_PKG "https://github.com/bhavyaalekhya/nudget/blob/main/backend/package.json"

    %% Database Layer
    subgraph "Database\nPrisma/SQLite" 
        SCHEMA["schema.prisma"]:::db
        MIGRATIONS["migrations/"]:::db
        MIG1["20250415234041_init/migration.sql"]:::db
        MIG2["20250502172124_remove_user/migration.sql"]:::db
        LOCK["migration_lock.toml"]:::db
    end
    click SCHEMA "https://github.com/bhavyaalekhya/nudget/blob/main/backend/prisma/schema.prisma"
    click MIGRATIONS "https://github.com/bhavyaalekhya/nudget/tree/main/backend/prisma/migrations/"
    click MIG1 "https://github.com/bhavyaalekhya/nudget/blob/main/backend/prisma/migrations/20250415234041_init/migration.sql"
    click MIG2 "https://github.com/bhavyaalekhya/nudget/blob/main/backend/prisma/migrations/20250502172124_remove_user/migration.sql"
    click LOCK "https://github.com/bhavyaalekhya/nudget/blob/main/backend/prisma/migrations/migration_lock.toml"

    %% Python Utilities
    subgraph "Python Utilities\n(Optional / Batch jobs)" 
        PY_APP["app.py"]:::ext
        PY_CAT["categorize.py"]:::ext
        REQ["requirements.txt"]:::ext
    end
    click PY_APP "https://github.com/bhavyaalekhya/nudget/blob/main/python-files/app.py"
    click PY_CAT "https://github.com/bhavyaalekhya/nudget/blob/main/python-files/categorize.py"
    click REQ "https://github.com/bhavyaalekhya/nudget/blob/main/python-files/requirements.txt"

    %% Relationships
    Electron -->|"loads Frontend URL"| FE_APP
    DevOps -->|"npm run dev / start"| Electron
    DevOps -->|"npm run dev"| FE_APP
    DevOps -->|"npm run dev"| BE_SERVER

    FE_APP -->|"HTTP REST (JSON)"| BE_SERVER
    BE_SERVER -->|"Prisma-generated SQL"| SCHEMA
    BE_SERVER -->|"gRPC/HTTP/Child Process I/O"| PY_APP

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef api fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef db fill:#ffe5b4,stroke:#333,stroke-width:1px;
    classDef ext fill:#e2e3e5,stroke:#333,stroke-width:1px;
    classDef devops fill:#f8d7da,stroke:#333,stroke-width:1px;
```
