# siddanth-6365/trackit-ai architecture

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

- Interactive diagram: https://gitdiagram.com/siddanth-6365/trackit-ai
- Repository: https://github.com/siddanth-6365/trackit-ai

## Overview

##### Project type and purpose
- This is a full-stack web application with a complementary Telegram bot.
- Purpose: turn receipt images into structured expense data (OCR → LLM parsing → Supabase), allow natural-language queries over spending, and expose both a browser UI (Next.js) and a Telegram interface.

##### Main components
a. Frontend (Next.js + Tailwind + shadcn/ui)
b. Backend API (FastAPI + asyncio in Python)
c. Telegram Bot (python-telegram-bot CLI)
d. External AI & OCR services
- Tesseract OCR engine
- meta-llama/llama-4 models API for receipt parsing
- sqlcoder-7b-2 via Cloudflare AI for NL→SQL
e. Database (Supabase PostgreSQL)

##### Component relationships & data flows
- Browser → Frontend UI → REST calls → Backend API
- Backend routers (`/receipts`, `/query`, `/users`) delegate to service layer
- Service layer modules:
- ocr_service.py calls Tesseract
- llm_service.py calls llama-4 API
- query_service.py calls sqlcoder API then executes on Postgres via supabase_client.py
- receipt_service.py orchestrates OCR → LLM → DB
- user_service.py handles auth & user data
- Backend → Supabase PostgreSQL (data storage)
- Telegram Bot → calls Backend endpoints (`/receipts/telegram_upload`, `/query/ask`) → same backend flow

##### Architectural patterns & design principles
- Layered architecture: Presentation (frontend/telegram), API gateway (routers), Domain logic (services), Data access (Supabase client)
- Async IO for high concurrency in Python
- Separation of concerns: routers vs. services vs. data client
- Stateless backend (all state in DB)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser UI
    subgraph "Browser (UI)" 
        direction TB
        UploadPage["Upload Page"]:::ui
        ReceiptsPage["Receipts List"]:::ui
        QueryPage["Query UI"]:::ui
        AnalyticsPage["Analytics"]:::ui
        LoginPage["Login"]:::ui
        SignupPage["Signup"]:::ui
    end

    %% Telegram Bot
    TelegramBot["Telegram Bot"]:::ui

    %% Backend Cluster
    subgraph "Backend API" 
        direction TB
        BackendEntry["main.py"]:::backend

        subgraph "API Gateway (Routers)"
            direction TB
            QueryRouter["/query router"]:::backend
            ReceiptsRouter["/receipts router"]:::backend
            UsersRouter["/users router"]:::backend
        end

        subgraph "Service Layer"
            direction TB
            OCRService["ocr_service.py"]:::backend
            LLMService["llm_service.py"]:::backend
            QueryService["query_service.py"]:::backend
            ReceiptService["receipt_service.py"]:::backend
            UserService["user_service.py"]:::backend
            SupabaseClient["supabase_client.py"]:::backend
        end
    end

    %% External Services & DB
    subgraph "External Services & DB"
        direction TB
        Tesseract["Tesseract OCR"]:::external
        LlamaAPI["Llama-4 API"]:::external
        CloudflareAI["Cloudflare AI (sqlcoder)"]:::external
        SupabaseDB["Supabase Postgres"]:::db
    end

    %% Data Flows - Receipt Ingestion
    UploadPage -->|"POST /receipts/save"| ReceiptsRouter
    ReceiptsRouter -->|"delegate"| ReceiptService
    ReceiptService -->|"OCR call"| OCRService
    OCRService -->|"image→text"| Tesseract
    ReceiptService -->|"LLM parse"| LLMService
    LLMService -->|"parsed data"| ReceiptService
    ReceiptService -->|"DB write"| SupabaseClient
    SupabaseClient -->|"INSERT"| SupabaseDB

    %% Data Flows - NL Query
    QueryPage -->|"POST /query/ask"| QueryRouter
    QueryRouter -->|"delegate"| QueryService
    QueryService -->|"generate SQL"| CloudflareAI
    CloudflareAI -->|"SQL"| QueryService
    QueryService -->|"DB read"| SupabaseClient
    SupabaseClient -->|"SELECT"| SupabaseDB
    QueryService -->|"response"| QueryRouter
    QueryRouter -->|"JSON"| QueryPage

    %% Telegram flows
    TelegramBot -->|"POST /receipts/telegram_upload"| ReceiptsRouter
    TelegramBot -->|"POST /query/ask"| QueryRouter

    %% Click Events
    click UploadPage "https://github.com/siddanth-6365/trackit-ai/blob/main/frontend/app/dashboard/upload/page.tsx"
    click ReceiptsPage "https://github.com/siddanth-6365/trackit-ai/blob/main/frontend/app/dashboard/receipts/page.tsx"
    click QueryPage "https://github.com/siddanth-6365/trackit-ai/blob/main/frontend/app/dashboard/query/page.tsx"
    click AnalyticsPage "https://github.com/siddanth-6365/trackit-ai/blob/main/frontend/app/dashboard/analytics/page.tsx"
    click LoginPage "https://github.com/siddanth-6365/trackit-ai/blob/main/frontend/app/login/page.tsx"
    click SignupPage "https://github.com/siddanth-6365/trackit-ai/blob/main/frontend/app/signup/page.tsx"
    click TelegramBot "https://github.com/siddanth-6365/trackit-ai/blob/main/telegram-bot/main.py"
    click BackendEntry "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/main.py"
    click QueryRouter "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/routers/query.py"
    click ReceiptsRouter "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/routers/receipts.py"
    click UsersRouter "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/routers/users.py"
    click OCRService "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/services/ocr_service.py"
    click LLMService "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/services/llm_service.py"
    click QueryService "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/services/query_service.py"
    click ReceiptService "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/services/receipt_service.py"
    click UserService "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/services/user_service.py"
    click SupabaseClient "https://github.com/siddanth-6365/trackit-ai/blob/main/backend/services/supabase_client.py"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#039BE5,stroke-width:1px
    classDef backend fill:#E8F5E9,stroke:#388E3C,stroke-width:1px
    classDef external fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
    classDef db fill:#EEEEEE,stroke:#616161,stroke-width:1px
```
