🧩 Components
A map of the codebase's major pieces and where they live.
🧭 Packages
| Path | Contents |
|---|---|
interfaces/openapi/ |
OpenAPI-first routing: app bootstrap, handlers, DTO schemas, middlewares |
interfaces/fetch_request/cli/ |
Argparse CLI over the fetch-request service (list, get, create-file, create-email, ambiguities, resolve, retry) |
interfaces/sse/ |
SSE ProgressEventBus and subscription endpoints |
interfaces/report/ |
Report generation endpoints and query models |
domain/ |
The three resource groups + enrichment + fetch pipeline (see below) |
domain/enrichment/ |
Entity identity/resolution + tag assignment; dagpipe-based pipelines |
domain/fetch_pipeline/ |
Fetch-request orchestration: pipeline, ambiguity, orchestrator, progress events |
domain/fetch_request/ |
FetchRequest model, file/email sources, bank enum, service |
infra/repos/ |
Mongo repositories (mongo-ops) for every domain model |
infra/adaptors/ |
Cache store, gitignore-safe secrets, fetch helpers |
infra/cache/ |
LRU maps, CacheableDict, Redis cache, TTL decorators |
infra/http_cache/ |
HTTP client cache layer with TTL + max-entries eviction |
infra/email/ |
IMAP email fetcher and parsed-mailbox traversal |
infra/llm/ |
OpenAI / OpenRouter provider pools, policy prompts, DTOs |
infra/adapters/sse.py |
SSE response adapter for progress event streaming |
pipelines/extraction/ |
Hexa runtime: pdf, csv, xlsx, email, llama extraction families |
pipelines/enrichment/ |
Pipeline node construction for entity/tag enrichment stages |
🏗 Domain Resource Groups
| Group | Models include | Purpose |
|---|---|---|
| users | User, UserActivity |
Actors; ownership of expenses/fetch requests |
| entities | Entity, EntityAccount |
Canonical payees with brands/branches |
| accounts | Account, AccountType |
Bank accounts owning expenses and statements |
| expenses | Expense, ExpenseKind, ExpenseSource, ExpenseTag |
The core normalized record |
| tags | Tag, TagColor |
Categorization labels with display colors |
| uploads | Upload |
Raw file/email ingest records |
| fetch_request | FetchRequest, FileSource, EmailSource, Bank |
Declares a statement ingestion job |
| report | Report, report models |
Aggregated outputs |
⚙️ Extraction Families (pipelines/extraction/)
| Family | Inputs | Notes |
|---|---|---|
pdf |
Bank statement PDFs | Heuristic, balance-driven reconciliation |
csv |
CSV exports | Axis/ICICI layouts first |
xlsx |
Excel exports | Tabular header+row parsing via openpyxl |
email |
IMAP mailboxes + attachments | EmailFetchingParadigm traversal |
llama |
Documents via LlamaParse | OCR + markdown distribution over pages |
All families share the hexa runtime: BaseExtractionPipeline, Fetcher, ExtractionStage, and the ambiguous flag — get_families_to_enrich returns families that should proceed to enrichment.
🔗 Related
Architecture · Domain Resources · Extraction Pipelines · Reports & Caching