Architecture

Tech Stack

High-Level Overview

graph TD
    User[User] -->|HTTP| Frontend[Frontend - HTML + HTMX]
    Frontend -->|API Calls| FastAPI[FastAPI Backend]
    FastAPI -->|Data Processing| Polars[Polars DataFrame]
    FastAPI -->|Storage| SQLite[SQLite Database]
    FastAPI -->|Auth| Cognito[AWS Cognito]
    FastAPI -->|Files| Storage[Local / S3]

Components

Backend (FastAPI)

• Handles HTTP requests and routing (app/routes/)
• Orchestrates data processing via Polars
• Serves server-rendered HTML via Jinja2

Data Processing (Polars)

• High-performance DataFrame library
• Used for transaction parsing, filtering, aggregation
• CSV/PDF import and transformation

Frontend

• Jinja2: Server-side template rendering
• HTMX: AJAX interactions without custom JavaScript
• Tailwind CSS + DaisyUI: Utility-first styling with component library
• Lucide: Icon set

Storage

• SQLite: Per-user database files in data/users/{user_id}/
• Filesystem: Uploaded files, rules YAML
• S3 (optional): Cloud storage backend when STORAGE_BACKEND=s3

Authentication

• AWS Cognito (optional): OAuth2 login flow
• Can be disabled for local development via environment config
• Routes: /login, /logout, /callback

Environment Modes

Set via ENV in .env file.