# arv100/finance-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/arv100/finance-tracker
- Repository: https://github.com/arv100/finance-tracker

## Overview

#### Purpose and Repository Shape
Finance-Tracker is a split frontend/backend application for recording, categorizing, viewing, and analyzing financial transactions. The repository has independent Python backend and Next.js frontend roots, plus sample import data at `dummy_data.csv`.

#### Backend API and Application Entry
The backend’s primary runtime entry point is `Backend/main.py`. It likely exposes the application/API surface and coordinates request handling with authentication, persistence, transaction schemas, and categorization.
- `Backend/main.py`
- `Backend/schemas.py`
- `Backend/requirements.txt`

#### Authentication Boundary
Authentication is isolated from the main application flow, providing a clear boundary between identity/access handling and financial-data operations. Backend routes or services should depend on this module rather than embedding credential logic.
- `Backend/auth.py`
- `Backend/main.py`
- `Backend/.env.example`

#### Persistence and Domain Data
Database access is centralized in `Backend/database.py`; request and response/domain shapes are defined separately in `Backend/schemas.py`. This separation makes the database layer the persistence boundary and schemas the API contract boundary.
- `Backend/database.py`
- `Backend/schemas.py`
- `Backend/main.py`

#### Categorization Pipeline
Transaction categorization is a dedicated backend capability rather than a frontend concern. Transaction input—manual entry or uploaded file data—should flow through the API into persistence and/or `Backend/categorization.py`, which owns classification behavior.
- `Backend/categorization.py`
- `Backend/schemas.py`
- `Backend/database.py`

#### Frontend Application and Routes
The frontend is a Next.js application with a root route, login route, and dashboard route. Shared layout establishes application-wide structure; dashboard-specific components compose the transaction-management and analytics experience.
- `Frontend/app/layout.tsx`
- `Frontend/app/login/page.tsx`
- `Frontend/app/dashboard/page.tsx`

#### Dashboard Data Flow
The dashboard contains distinct presentation stages for transaction entry, file import, tabular transaction display, summary cards, and analytics charts. API communication is centralized in the frontend client boundary rather than distributed across UI components.
- `Frontend/lib/api.ts`
- `Frontend/components/dashboard/transaction-form.tsx`
- `Frontend/components/dashboard/file-uploader.tsx`
- `Frontend/components/dashboard/data-table.tsx`
- `Frontend/components/dashboard/analytics-charts.tsx`

#### Runtime and Infrastructure Boundaries
The frontend uses the Node.js/Next.js ecosystem (`Frontend/package.json`) and includes query/theme providers for cross-cutting client behavior. The backend uses Python dependency management (`Backend/pyproject.toml`, `Backend/uv.lock`) and environment-based configuration. The database technology and external authentication provider cannot be determined from the supplied tree.
- `Frontend/components/query-provider.tsx`
- `Frontend/package.json`
- `Backend/pyproject.toml`

Main entry points: [`Backend/main.py`](https://github.com/arv100/finance-tracker/blob/main/Backend/main.py) (Backend API), [`Frontend/lib/api.ts`](https://github.com/arv100/finance-tracker/blob/main/Frontend/lib/api.ts) (API client), [`Frontend/app/dashboard/page.tsx`](https://github.com/arv100/finance-tracker/blob/main/Frontend/app/dashboard/page.tsx) (Dashboard route), [`Frontend/app/layout.tsx`](https://github.com/arv100/finance-tracker/blob/main/Frontend/app/layout.tsx) (Shared layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js Frontend"]
  node_layout["Shared layout<br/>Next.js layout<br/>[layout.tsx]"]
  node_providers["Query &amp; theme providers<br/>client providers<br/>[query-provider.tsx]"]
  node_login["Login route<br/>Next.js route<br/>[page.tsx]"]
  node_dashboard["Dashboard route<br/>Next.js route<br/>[page.tsx]"]
  node_api_client["API client<br/>frontend API boundary<br/>[api.ts]"]
  node_transaction_form["Transaction entry<br/>dashboard component"]
  node_file_uploader["File import<br/>dashboard component<br/>[file-uploader.tsx]"]
  node_data_table["Transaction table<br/>dashboard component<br/>[data-table.tsx]"]
  node_analytics["Analytics charts<br/>dashboard component"]
  node_frontend_runtime["Next.js runtime<br/>Node.js dependencies<br/>[package.json]"]
end

subgraph group_backend["Python Backend"]
  node_api{{"Backend API<br/>Python application entry<br/>[main.py]"}}
  node_auth["Authentication<br/>identity boundary<br/>[auth.py]"]
  node_schemas["API schemas<br/>domain contracts<br/>[schemas.py]"]
  node_categorization["Categorization<br/>classification service<br/>[categorization.py]"]
  node_database[("Database access<br/>persistence boundary<br/>[database.py]")]
  node_backend_env["Backend environment<br/>environment configuration<br/>[.env.example]"]
  node_backend_runtime["Python runtime<br/>Python dependencies<br/>[pyproject.toml]"]
end

node_sample_csv["Sample import data<br/>CSV data<br/>[dummy_data.csv]"]

node_layout -->|"wraps"| node_providers
node_layout -->|"hosts"| node_login
node_layout -->|"hosts"| node_dashboard
node_dashboard -->|"composes"| node_transaction_form
node_dashboard -->|"composes"| node_file_uploader
node_dashboard -->|"composes"| node_data_table
node_dashboard -->|"composes"| node_analytics
node_login -->|"auth requests"| node_api_client
node_transaction_form -->|"submits transactions"| node_api_client
node_file_uploader -->|"uploads imports"| node_api_client
node_data_table -->|"loads transactions"| node_api_client
node_analytics -->|"loads analytics"| node_api_client
node_sample_csv -.->|"example input"| node_file_uploader
node_api_client -->|"HTTP API"| node_api
node_api -->|"authorizes requests"| node_auth
node_api -->|"validates contracts"| node_schemas
node_api -->|"categorizes imports"| node_categorization
node_api -->|"reads and writes"| node_database
node_categorization -->|"uses transaction shapes"| node_schemas
node_categorization -->|"updates classified data"| node_database
node_backend_env -.->|"configures"| node_api
node_frontend_runtime -.->|"runs"| node_layout
node_backend_runtime -.->|"runs"| node_api

click node_layout "https://github.com/arv100/finance-tracker/blob/main/Frontend/app/layout.tsx"
click node_providers "https://github.com/arv100/finance-tracker/blob/main/Frontend/components/query-provider.tsx"
click node_login "https://github.com/arv100/finance-tracker/blob/main/Frontend/app/login/page.tsx"
click node_dashboard "https://github.com/arv100/finance-tracker/blob/main/Frontend/app/dashboard/page.tsx"
click node_api_client "https://github.com/arv100/finance-tracker/blob/main/Frontend/lib/api.ts"
click node_transaction_form "https://github.com/arv100/finance-tracker/blob/main/Frontend/components/dashboard/transaction-form.tsx"
click node_file_uploader "https://github.com/arv100/finance-tracker/blob/main/Frontend/components/dashboard/file-uploader.tsx"
click node_data_table "https://github.com/arv100/finance-tracker/blob/main/Frontend/components/dashboard/data-table.tsx"
click node_analytics "https://github.com/arv100/finance-tracker/blob/main/Frontend/components/dashboard/analytics-charts.tsx"
click node_sample_csv "https://github.com/arv100/finance-tracker/blob/main/dummy_data.csv"
click node_api "https://github.com/arv100/finance-tracker/blob/main/Backend/main.py"
click node_auth "https://github.com/arv100/finance-tracker/blob/main/Backend/auth.py"
click node_schemas "https://github.com/arv100/finance-tracker/blob/main/Backend/schemas.py"
click node_categorization "https://github.com/arv100/finance-tracker/blob/main/Backend/categorization.py"
click node_database "https://github.com/arv100/finance-tracker/blob/main/Backend/database.py"
click node_backend_env "https://github.com/arv100/finance-tracker/blob/main/Backend/.env.example"
click node_frontend_runtime "https://github.com/arv100/finance-tracker/blob/main/Frontend/package.json"
click node_backend_runtime "https://github.com/arv100/finance-tracker/blob/main/Backend/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_layout,node_providers,node_login,node_dashboard,node_api_client,node_transaction_form,node_file_uploader,node_data_table,node_analytics,node_frontend_runtime toneBlue
class node_api,node_auth,node_schemas,node_categorization,node_database,node_backend_env,node_backend_runtime toneAmber
class node_sample_csv toneNeutral
```

## Components

### Next.js Frontend

- [Shared layout](https://github.com/arv100/finance-tracker/blob/main/Frontend/app/layout.tsx): Next.js layout · Establishes application-wide structure. · `Frontend/app/layout.tsx`
- [Query & theme providers](https://github.com/arv100/finance-tracker/blob/main/Frontend/components/query-provider.tsx): client providers · Provides cross-cutting client behavior. · `Frontend/components/query-provider.tsx`
- [Login route](https://github.com/arv100/finance-tracker/blob/main/Frontend/app/login/page.tsx): Next.js route · `Frontend/app/login/page.tsx`
- [Dashboard route](https://github.com/arv100/finance-tracker/blob/main/Frontend/app/dashboard/page.tsx): Next.js route · Composes transaction management and analytics. · `Frontend/app/dashboard/page.tsx`
- [API client](https://github.com/arv100/finance-tracker/blob/main/Frontend/lib/api.ts): frontend API boundary · Centralizes backend communication. · `Frontend/lib/api.ts`
- [Transaction entry](https://github.com/arv100/finance-tracker/blob/main/Frontend/components/dashboard/transaction-form.tsx): dashboard component · `Frontend/components/dashboard/transaction-form.tsx`
- [File import](https://github.com/arv100/finance-tracker/blob/main/Frontend/components/dashboard/file-uploader.tsx): dashboard component · `Frontend/components/dashboard/file-uploader.tsx`
- [Transaction table](https://github.com/arv100/finance-tracker/blob/main/Frontend/components/dashboard/data-table.tsx): dashboard component · `Frontend/components/dashboard/data-table.tsx`
- [Analytics charts](https://github.com/arv100/finance-tracker/blob/main/Frontend/components/dashboard/analytics-charts.tsx): dashboard component · `Frontend/components/dashboard/analytics-charts.tsx`
- [Next.js runtime](https://github.com/arv100/finance-tracker/blob/main/Frontend/package.json): Node.js dependencies · `Frontend/package.json`

### Python Backend

- [Backend API](https://github.com/arv100/finance-tracker/blob/main/Backend/main.py): Python application entry · Exposes financial-data operations and coordinates backend services. · `Backend/main.py`
- [Authentication](https://github.com/arv100/finance-tracker/blob/main/Backend/auth.py): identity boundary · Separates access handling from financial-data operations. · `Backend/auth.py`
- [API schemas](https://github.com/arv100/finance-tracker/blob/main/Backend/schemas.py): domain contracts · Defines request, response, and transaction shapes. · `Backend/schemas.py`
- [Categorization](https://github.com/arv100/finance-tracker/blob/main/Backend/categorization.py): classification service · Classifies transaction data. · `Backend/categorization.py`
- [Database access](https://github.com/arv100/finance-tracker/blob/main/Backend/database.py): persistence boundary · Centralizes financial-data persistence. · `Backend/database.py`
- [Backend environment](https://github.com/arv100/finance-tracker/blob/main/Backend/.env.example): environment configuration · Supplies backend runtime configuration. · `Backend/.env.example`
- [Python runtime](https://github.com/arv100/finance-tracker/blob/main/Backend/pyproject.toml): Python dependencies · `Backend/pyproject.toml`

### Other components

- [Sample import data](https://github.com/arv100/finance-tracker/blob/main/dummy_data.csv): CSV data · `dummy_data.csv`

## Connections

- Shared layout → Query & theme providers: wraps
- Shared layout → Login route: hosts
- Shared layout → Dashboard route: hosts
- Dashboard route → Transaction entry: composes
- Dashboard route → File import: composes
- Dashboard route → Transaction table: composes
- Dashboard route → Analytics charts: composes
- Login route → API client: auth requests
- Transaction entry → API client: submits transactions
- File import → API client: uploads imports
- Transaction table → API client: loads transactions
- Analytics charts → API client: loads analytics
- Sample import data → File import: example input
- API client → Backend API: HTTP API
- Backend API → Authentication: authorizes requests
- Backend API → API schemas: validates contracts
- Backend API → Categorization: categorizes imports
- Backend API → Database access: reads and writes
- Categorization → API schemas: uses transaction shapes
- Categorization → Database access: updates classified data
- Backend environment → Backend API: configures
- Next.js runtime → Shared layout: runs
- Python runtime → Backend API: runs