How lakshya0010/insightforge works
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: router.py v1 router · statement_service.py Statement service · user_service.py User service · user_repo.py User repo
Components 22
Streamlit UI
Thin client that calls the backend over HTTP.
- Streamlit app · User-facing interface for upload and retrieval flows.
ui/streamlit_app.py - API 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 · Starts FastAPI and wires the versioned router.
app/main.py - v1 router · Top-level HTTP surface for auth and statement endpoints.
app/api/v1/router.py - Auth API · Register, login, and current-user routes.
app/api/v1/router.py - Statement API · Upload statements, list statements, and fetch details.
app/api/v1/router.py - Dependencies · Injects authenticated user and shared request dependencies.
app/core/dependencies.py - Security · JWT creation/verification and password hashing.
app/core/security.py - Config · Central environment and runtime configuration.
app/core/config.py - Errors · Global exception handling and API error mapping.
app/core/exceptions.py - User service · Coordinates user registration and authentication flows.
app/services/user_service.py - Statement service · Orchestrates upload, parsing, categorization, and report generation.
app/services/statement_service.py - Parser · Transforms uploaded CSVs into normalized statement data.
app/services/parser_service.py - User repo · Database access for users and auth lookup.
app/repositories/user_repo.py - Statement repo · Database access for statements, transactions, and reports.
app/repositories/statement_repo.py - User model · SQLAlchemy entity for user persistence.
app/models/user.py - Statement model · SQLAlchemy entities for statements and related artifacts.
app/models/statement.py - Schemas · Request/response schemas for auth and statement APIs.
app/schemas/statement.py
Infrastructure
Database, migrations, and external AI dependency.
- Async DB · Async engine and session factory for PostgreSQL access.
app/core/database.py - LLM service · LangChain + Groq integration for categorization and narrative reports.
app/services/llm_service.py - Alembic migrations · Database migration track for users, statements, reports, and summary fields.
alembic/versions - PostgreSQL · Durable application store for users and statement history.
Connections 23
- 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.