LARGO is a self-hosted personal finance and task management system. Photograph a receipt, type a transaction, create a task — the AI pipeline structures everything and surfaces it in a clean dashboard. No cloud storage. No subscriptions. Your data stays on your machine.

• Receipt scanning — photograph any NF-e; Gemini extracts total, items, CNPJ and date automatically
• Natural language input — type expenses and tasks in plain text; the AI structures them for you
• Financial dashboard — spending by category, monthly evolution, and custom date ranges
• Task management — create, track and close tasks from the same interface
• Real-time feedback — WebSocket notifications when AI processing completes
• Privacy-first — all data lives locally; only AI inference calls reach external APIs

LARGO follows a Microservices Lite pattern orchestrated by Docker Compose, with an internal network isolating all inter-service communication.

┌─────────────────────────────────────────────┐
│                   localhost                 │
│                                             │
│  ┌───────────┐          ┌────────────────┐  │
│  │    web    │◄────────►│    gateway     │  │
│  │ React/Bun │  REST +  │   Rust/Axum    │  │
│  └───────────┘    WS    └───────┬────────┘  │
│                                 │           │
│                       ┌─────────┴────────┐  │
│                       │                  │  │
│               ┌───────▼──────┐  ┌────────▼─┤│
│               │  ai-worker   │  │  MongoDB ││
│               │  Python/     │  │          ││
│               │  FastAPI     │  └──────────┘│
│               └──────┬───────┘              │
└──────────────────────┼──────────────────────┘
                       │
              ┌────────▼────────┐
              │   Google AI     │
              │  Gemini Flash   │  ← images (NF-e OCR)
              │  Gemini Flash   │
              │      Lite       │  ← text (natural language)
              └─────────────────┘

• Backend — Hexagonal Architecture (Ports & Adapters): domain logic is fully decoupled from infrastructure (GeminiAdapter, MongoAdapter, AxumRouter).
• Frontend — Feature-Based Architecture: code is organized by business module (Finance, Tasks) with presentational components and custom hooks that isolate all API/state logic.
• AI prompts — TOON (Token-Oriented Object Notation): structured context sent to Gemini uses a compact token-efficient encoding (~40% fewer tokens vs raw JSON).

Photo → gateway → ai-worker → Gemini Flash (image OCR)
                             → TOON-encoded context
                             → Gemini Flash Lite (structuring)
                             → { total, itens[], data, cnpj, estabelecimento }
                             → MongoDB ← gateway ← WebSocket notification → web

• Docker and Docker Compose
• A Google AI Studio API key (Gemini)

git clone https://github.com/seuusuario/largo.git
cd largo
cp .env.example .env
# fill in your credentials
docker compose up --build

Open http://localhost:5173.

See .env.example for the full list.

largo/
├── gateway/           # Rust/Axum — API gateway (Hexagonal Architecture)
├── ai-worker/         # Python/FastAPI — Gemini OCR + TOON prompt pipeline
├── web/               # React/Bun/Vite — dashboard (Feature-Based Architecture)
├── docs/              # ADRs, TOON prompt schemas, database specs
├── docker-compose.yml
└── .env.example

Key docs:

• docs/architecture/adr/ — architectural decision records
• docs/ai/prompts.md — TOON prompt schemas and examples
• docs/database/setup.md — index and validator setup

Contributions are welcome. Before submitting a pull request for significant changes, please open an issue to discuss scope.

• Record architectural decisions as ADRs in docs/architecture/adr/.
• Update docs/ai/prompts.md whenever a Gemini prompt schema changes.
• Keep .env.example in sync with any new environment variables.

MIT