Skip to content

📦 Domain Resources

Each resource group is a domain package with models, ports (abstract repositories/services), and a service implementation — a facade over the repo. Everything is defined by GSDFC docstrings and mirrored as .pyi stubs.

👤 Users

  • User — id, name, email, phone, password hash, avatar.
  • UserActivity — audit trail of user-driven actions.
  • Service: UserService (create, read, update, delete, activity log). Routes: GET/POST /users, GET/PATCH/DELETE /users/{id}, activity listing under /users/{id}/activities.

🏢 Entities

  • Entity — canonical payee: name, brands, branch, aliases, classification, type.
  • EntityAccount — an account known to belong to an entity.
  • Service: EntityService — entity creation, name-based lookup, account linking. Routes: GET/POST /entities, GET/PATCH /entities/{id}, POST /entities/{id}/accounts.

🏦 Accounts

  • Account — bank account: name, account number, bank, currency, account type, iban, linked entity.
  • AccountType — savings / current / credit etc.
  • Service: AccountService — create, read, update, delete, balance helpers. Routes: GET/POST /accounts, GET/PATCH/DELETE /accounts/{id}.

🧾 Expenses

  • Expense — the core record: amount, balance, kind (debit/credit/transfer), mcc, memo, date, tag, entity, source.
  • ExpenseTag — tag membership on an expense; ExpenseSource — provenance (upload/fetch-request).
  • Service: ExpenseService — CRUD plus tag assignment and entity resolution. Routes: GET/POST /expenses, GET/PATCH/DELETE /expenses/{id}, tag/entity mutation sub-routes.

🏷 Tags

  • Tag — name, color, optional description.
  • TagColor — palette enum for display.
  • Service: TagService — CRUD. Routes: GET/POST /tags, GET/PATCH/DELETE /tags/{id}.

📤 Uploads

  • Upload — records a raw statement upload (file or email) with status.
  • Service: UploadService — create, read, update status, list. Routes under /uploads.

📥 Fetch Request

  • FetchRequest — a statement ingestion job: user, account, source (file/email), date range, status, retry count.
  • FileSource — path + optional bank; EmailSource — mailbox + filters; Bank — enum of supported banks.
  • Service: FetchRequestService — CRUD + status transitions (update_status). Routes: GET/POST /fetch-requests, GET/PATCH /fetch-requests/{id}, POST /fetch-requests/{id}/retry.

🔁 Repositories (Ports)

Every group declares abstract repo ports (Ports: db.py, service.py) in the domain and implements them in infra/repos/ with mongo-ops. Repos support:

  • filter-based queries — search(filter={...}, limit=...)
  • explicit FK population — x-fk resolves referenced ids via exact filters
  • cache invalidation — writes clear the in-memory LRU

Shared wiring lives in facades.py (domain) and repositories.py (infra). The service registry keys used in init.py are the string names passed to get_svc(...).

Components · Enrichment · Reports & Caching