# lakshya0010/insightforge architecture

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

- Interactive diagram: https://gitdiagram.com/lakshya0010/insightforge
- Repository: https://github.com/lakshya0010/insightforge

## Overview

1. **This repo is split into two deployable apps:** a FastAPI backend under `app/` and a Streamlit UI under `ui/`. The UI is a thin client that talks to the backend over HTTP; it does not own business logic or persistence.

2. **The backend is organized as a layered system:** `api/v1` handles HTTP routing, `services` contains business workflows, `repositories` isolates database access, `models` defines SQLAlchemy ORM entities, and `schemas` defines Pydantic request/response contracts. This is the main boundary pattern to reflect in a diagram.

3. **Request entrypoint and API surface:** `app/main.py` boots the FastAPI application and wires the v1 router from `app/api/v1/router.py`. The exposed API is centered on auth and statement analysis: register/login, current-user lookup, upload statement, list statements, and fetch statement details.

4. **Authentication is user-based and token-driven.** `app/core/security.py` handles JWT creation/verification plus password hashing, while `app/core/dependencies.py` likely injects the authenticated user into protected routes. User persistence lives in `user_repo.py` and the `user.py` model, with Alembic migrations showing user-table evolution.

5. **The core product flow is the statement analysis pipeline.** A CSV upload enters the statement service, is parsed by `parser_service.py`, persisted through the statement repository, categorized by the LLM service, then summarized into a plain-English report and saved back to the database. The UI should be drawn as invoking one upload endpoint and later reading the resulting statement/report data.

6. **LLM integration is a distinct subsystem.** `app/services/llm_service.py` integrates LangChain with Groq (Llama 3.3-70b per the README). It is used for two tasks: batch transaction categorization and narrative report generation. This is an external dependency boundary separate from the database and HTTP layers.

7. **Persistence is PostgreSQL via async SQLAlchemy.** `app/core/database.py` provides the async engine/session, and repositories encapsulate all SQL access. The README and migrations indicate the data model stores users plus statement-related artifacts such as transactions, reports, and top-transfer summary data.

8. **Schema evolution is managed with Alembic.** The `alembic/versions` files show the domain schema changing over time: initial users, hashed passwords, and later additions for statements/transactions/reports and top-transfers fields. In an architecture diagram, this is the “database migration” track feeding PostgreSQL.

9. **Cross-cutting infrastructure lives in `core/`.** `config.py` centralizes environment configuration, `exceptions.py` defines global error handling, and `logging.py` sets structured logging. These are support services used by the API, services, and repositories rather than separate business components.

10. **Deployment is container-first.** `Dockerfile` and `docker-compose.yml` run the backend and database together locally; `Dockerfile.ui` packages the Streamlit frontend. The README’s Railway deployment means the production topology is backend + managed PostgreSQL + external Groq API, with the UI calling the backend over the network.

11. **Key data boundary:** CSV input is transformed into normalized statement data, then into categorized transaction insights, then into a saved report. The important architecture diagram should show that the CSV itself is transient input, while the database becomes the durable source of truth for history and retrieval.

12. **Main external services:** PostgreSQL stores application state, and Groq provides the AI inference capability. Everything else in the repo is orchestration around those two dependencies.

Main entry points: [`app/api/v1/router.py`](https://github.com/lakshya0010/insightforge/blob/main/app/api/v1/router.py) (v1 router), [`app/services/statement_service.py`](https://github.com/lakshya0010/insightforge/blob/main/app/services/statement_service.py) (Statement service), [`app/services/user_service.py`](https://github.com/lakshya0010/insightforge/blob/main/app/services/user_service.py) (User service), [`app/repositories/user_repo.py`](https://github.com/lakshya0010/insightforge/blob/main/app/repositories/user_repo.py) (User repo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Streamlit UI"]
  node_ui_app["Streamlit app<br/>ui<br/>[streamlit_app.py]"]
  node_ui_client["API client<br/>http client<br/>[api_client.py]"]
end

subgraph group_backend["FastAPI backend"]
  node_main["App entry<br/>fastapi boot<br/>[main.py]"]
  node_api_router["v1 router<br/>api routing<br/>[router.py]"]
  node_auth_api["Auth API<br/>endpoint group<br/>[router.py]"]
  node_statement_api["Statement API<br/>endpoint group<br/>[router.py]"]
  node_deps["Dependencies<br/>auth deps<br/>[dependencies.py]"]
  node_security["Security<br/>jwt + hashing<br/>[security.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_errors["Errors<br/>error handling<br/>[exceptions.py]"]
  node_user_service["User service<br/>workflow<br/>[user_service.py]"]
  node_statement_service["Statement service<br/>workflow"]
  node_parser_service["Parser<br/>csv parsing<br/>[parser_service.py]"]
  node_user_repo["User repo<br/>[user_repo.py]"]
  node_statement_repo["Statement repo<br/>[statement_repo.py]"]
  node_user_model["User model<br/>orm model<br/>[user.py]"]
  node_statement_model["Statement model<br/>orm model<br/>[statement.py]"]
  node_schemas["Schemas<br/>pydantic contracts<br/>[statement.py]"]
end

subgraph group_infra["Infrastructure"]
  node_database[("Async DB<br/>sqlalchemy async<br/>[database.py]")]
  node_llm_service{{"LLM service<br/>ai integration<br/>[llm_service.py]"}}
  node_migrations["Alembic migrations<br/>schema evolution"]
  node_postgres[("PostgreSQL<br/>database")]
end

node_ui_app -->|"calls backend"| node_ui_client
node_ui_client -->|"HTTP requests"| node_api_router
node_main -->|"mounts"| node_api_router
node_api_router -->|"exposes"| node_auth_api
node_api_router -->|"exposes"| node_statement_api
node_auth_api -->|"uses"| node_deps
node_statement_api -->|"uses"| node_deps
node_auth_api -->|"delegates"| node_user_service
node_statement_api -->|"delegates"| node_statement_service
node_user_service -->|"hashes/tokens"| node_security
node_user_service -->|"persists"| node_user_repo
node_statement_service -->|"parses"| node_parser_service
node_statement_service -->|"categorizes"| node_llm_service
node_statement_service -->|"persists"| node_statement_repo
node_user_repo -->|"queries"| node_database
node_statement_repo -->|"queries"| node_database
node_user_repo -->|"maps to"| node_user_model
node_statement_repo -->|"maps to"| node_statement_model
node_api_router -->|"validates"| node_schemas
node_migrations -->|"evolves"| node_postgres
node_config -.->|"configures"| node_main
node_errors -.->|"handles"| node_api_router
node_ui_app -.->|"upload/read"| node_statement_api

click node_ui_app "https://github.com/lakshya0010/insightforge/blob/main/ui/streamlit_app.py"
click node_ui_client "https://github.com/lakshya0010/insightforge/blob/main/ui/api_client.py"
click node_main "https://github.com/lakshya0010/insightforge/blob/main/app/main.py"
click node_api_router "https://github.com/lakshya0010/insightforge/blob/main/app/api/v1/router.py"
click node_auth_api "https://github.com/lakshya0010/insightforge/blob/main/app/api/v1/router.py"
click node_statement_api "https://github.com/lakshya0010/insightforge/blob/main/app/api/v1/router.py"
click node_deps "https://github.com/lakshya0010/insightforge/blob/main/app/core/dependencies.py"
click node_security "https://github.com/lakshya0010/insightforge/blob/main/app/core/security.py"
click node_config "https://github.com/lakshya0010/insightforge/blob/main/app/core/config.py"
click node_errors "https://github.com/lakshya0010/insightforge/blob/main/app/core/exceptions.py"
click node_database "https://github.com/lakshya0010/insightforge/blob/main/app/core/database.py"
click node_user_service "https://github.com/lakshya0010/insightforge/blob/main/app/services/user_service.py"
click node_statement_service "https://github.com/lakshya0010/insightforge/blob/main/app/services/statement_service.py"
click node_parser_service "https://github.com/lakshya0010/insightforge/blob/main/app/services/parser_service.py"
click node_llm_service "https://github.com/lakshya0010/insightforge/blob/main/app/services/llm_service.py"
click node_user_repo "https://github.com/lakshya0010/insightforge/blob/main/app/repositories/user_repo.py"
click node_statement_repo "https://github.com/lakshya0010/insightforge/blob/main/app/repositories/statement_repo.py"
click node_user_model "https://github.com/lakshya0010/insightforge/blob/main/app/models/user.py"
click node_statement_model "https://github.com/lakshya0010/insightforge/blob/main/app/models/statement.py"
click node_schemas "https://github.com/lakshya0010/insightforge/blob/main/app/schemas/statement.py"
click node_migrations "https://github.com/lakshya0010/insightforge/tree/main/alembic/versions"

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_ui_app,node_ui_client toneBlue
class node_main,node_api_router,node_auth_api,node_statement_api,node_deps,node_security,node_config,node_errors,node_user_service,node_statement_service,node_parser_service,node_user_repo,node_statement_repo,node_user_model,node_statement_model,node_schemas toneAmber
class node_database,node_llm_service,node_migrations,node_postgres toneMint
```

## Components

### Streamlit UI

Thin client that calls the backend over HTTP.

- [Streamlit app](https://github.com/lakshya0010/insightforge/blob/main/ui/streamlit_app.py): ui · User-facing interface for upload and retrieval flows. · `ui/streamlit_app.py`
- [API client](https://github.com/lakshya0010/insightforge/blob/main/ui/api_client.py): http client · HTTP wrapper used by the UI to talk to the backend. · `ui/api_client.py`

### FastAPI backend

Layered API, service, repository, and domain model stack.

- [App entry](https://github.com/lakshya0010/insightforge/blob/main/app/main.py): fastapi boot · Starts FastAPI and wires the versioned router. · `app/main.py`
- [v1 router](https://github.com/lakshya0010/insightforge/blob/main/app/api/v1/router.py): api routing · Top-level HTTP surface for auth and statement endpoints. · `app/api/v1/router.py`
- [Auth API](https://github.com/lakshya0010/insightforge/blob/main/app/api/v1/router.py): endpoint group · Register, login, and current-user routes. · `app/api/v1/router.py`
- [Statement API](https://github.com/lakshya0010/insightforge/blob/main/app/api/v1/router.py): endpoint group · Upload statements, list statements, and fetch details. · `app/api/v1/router.py`
- [Dependencies](https://github.com/lakshya0010/insightforge/blob/main/app/core/dependencies.py): auth deps · Injects authenticated user and shared request dependencies. · `app/core/dependencies.py`
- [Security](https://github.com/lakshya0010/insightforge/blob/main/app/core/security.py): jwt + hashing · JWT creation/verification and password hashing. · `app/core/security.py`
- [Config](https://github.com/lakshya0010/insightforge/blob/main/app/core/config.py): settings · Central environment and runtime configuration. · `app/core/config.py`
- [Errors](https://github.com/lakshya0010/insightforge/blob/main/app/core/exceptions.py): error handling · Global exception handling and API error mapping. · `app/core/exceptions.py`
- [User service](https://github.com/lakshya0010/insightforge/blob/main/app/services/user_service.py): workflow · Coordinates user registration and authentication flows. · `app/services/user_service.py`
- [Statement service](https://github.com/lakshya0010/insightforge/blob/main/app/services/statement_service.py): workflow · Orchestrates upload, parsing, categorization, and report generation. · `app/services/statement_service.py`
- [Parser](https://github.com/lakshya0010/insightforge/blob/main/app/services/parser_service.py): csv parsing · Transforms uploaded CSVs into normalized statement data. · `app/services/parser_service.py`
- [User repo](https://github.com/lakshya0010/insightforge/blob/main/app/repositories/user_repo.py): repository · Database access for users and auth lookup. · `app/repositories/user_repo.py`
- [Statement repo](https://github.com/lakshya0010/insightforge/blob/main/app/repositories/statement_repo.py): repository · Database access for statements, transactions, and reports. · `app/repositories/statement_repo.py`
- [User model](https://github.com/lakshya0010/insightforge/blob/main/app/models/user.py): orm model · SQLAlchemy entity for user persistence. · `app/models/user.py`
- [Statement model](https://github.com/lakshya0010/insightforge/blob/main/app/models/statement.py): orm model · SQLAlchemy entities for statements and related artifacts. · `app/models/statement.py`
- [Schemas](https://github.com/lakshya0010/insightforge/blob/main/app/schemas/statement.py): pydantic contracts · Request/response schemas for auth and statement APIs. · `app/schemas/statement.py`

### Infrastructure

Database, migrations, and external AI dependency.

- [Async DB](https://github.com/lakshya0010/insightforge/blob/main/app/core/database.py): sqlalchemy async · Async engine and session factory for PostgreSQL access. · `app/core/database.py`
- [LLM service](https://github.com/lakshya0010/insightforge/blob/main/app/services/llm_service.py): ai integration · LangChain + Groq integration for categorization and narrative reports. · `app/services/llm_service.py`
- [Alembic migrations](https://github.com/lakshya0010/insightforge/tree/main/alembic/versions): schema evolution · Database migration track for users, statements, reports, and summary fields. · `alembic/versions`
- **PostgreSQL**: database · Durable application store for users and statement history.

## Connections

- Streamlit app → API client: calls backend · UI submits auth and statement requests through the client.
- API client → v1 router: HTTP requests · Client talks to the backend API over the network.
- App entry → v1 router: mounts · Application startup wires the versioned router.
- v1 router → Auth API: exposes · Router publishes auth endpoints.
- v1 router → Statement API: exposes · Router publishes statement endpoints.
- Auth API → Dependencies: uses · Protected auth routes inject the current user.
- Statement API → Dependencies: uses · Protected statement routes depend on auth context.
- Auth API → User service: delegates · HTTP layer forwards auth workflows to the service layer.
- Statement API → Statement service: delegates · HTTP layer forwards upload and retrieval workflows to the service layer.
- User service → Security: hashes/tokens · Service uses security helpers for passwords and JWTs.
- User service → User repo: persists · User workflows read and write through the repository.
- Statement service → Parser: parses · Uploads are normalized before persistence.
- Statement service → LLM service: categorizes · Transactions and reports are enriched by LLM inference.
- Statement service → Statement repo: persists · Statement lifecycle data is saved through the repository.
- User repo → Async DB: queries · Repository executes async SQL operations.
- Statement repo → Async DB: queries · Repository executes async SQL operations.
- User repo → User model: maps to · Repository reads and writes user entities.
- Statement repo → Statement model: maps to · Repository reads and writes statement-related entities.
- v1 router → Schemas: validates · API layer uses request and response contracts.
- Alembic migrations → PostgreSQL: evolves · Alembic manages the live database schema.
- Config → App entry: configures · Runtime settings are consumed at startup.
- Errors → v1 router: handles · Global error mapping applies across the API surface.
- Streamlit app → Statement API: upload/read · UI depends on statement endpoints for the core product flow.