Architecture

The project follows the same Clean Architecture as every Apogee-generated app. Layered, dependency-rule respected:

flowchart TB
  subgraph presentation
    api[FastAPI routers]
    cli[Custom CLIs]
  end
  subgraph application
    use_cases[Use cases]
  end
  subgraph domain
    entities[Entities + Value Objects]
    ports[Repository ports]
  end
  subgraph infrastructure
    pg[Postgres repos]
    mongo[Mongo repos]
    qdrant[Qdrant store]
    auth[apogee-auth]
    rag[apogee-ai-rag]
  end

  api --> use_cases
  cli --> use_cases
  use_cases --> ports
  pg -.implements.-> ports
  mongo -.implements.-> ports
  qdrant -.implements.-> ports
  api -. wires .- pg
  api -. wires .- mongo
  api -. wires .- qdrant
  api -. wires .- auth
  use_cases -. uses .- rag

Multi-currency

Money is stored in minor units (int) plus an ISO-4217 currency code. FX conversions read the most recent FxRateEntity per (base, quote) pair.

Python

@dataclass
class AccountEntity(BaseEntity):
    iban: str
    balance_minor: int
    currency: str  # "USD", "EUR", "BRL", "CNY"
    ...

Multi-language

Customer-facing strings (T&Cs, statements, support replies) are stored in JSONB columns keyed by ISO-639-1 language code. The RAG knowledge base ingests the same content per language so the compliance assistant can answer in the customer's preferred language.

RAG over compliance regulations

Documents (in 4 languages) → chunked → embedded → Qdrant. At query time, the compliance officer agent retrieves top-k chunks and asks the LLM to summarize / cite. Implemented via apogee-ai-rag.

Auth and audit

apogee-auth provides RBAC with these roles:

• customer — read own data
• teller — read all customers, post transactions ≤ threshold
• compliance_officer — read flagged transactions, raise/dismiss flags
• admin — manage users, roles, MFA

Every authenticated request is logged in MongoDB via the audit middleware.