Architecture overview

core-api follows a conventional layered FastAPI structure:

app/
  api/
    deps.py     shared FastAPI dependencies (DbSession, current user/tenant)
    v1/         versioned router + route handlers (app/api/v1/routes/)
  core/         settings, auth/permissions, rate limiting, scheduler, locks
  db/           async SQLAlchemy engine, session, declarative base
  models/       ORM models
  schemas/      Pydantic request/response models
  search/       Meilisearch quick-search index + database fallback
  services/     business logic / validation, one module per domain
  main.py       FastAPI app instance (lifespan creates platform roles, starts the scheduler)
migrations/     Alembic migrations

Domain pages: Accounts, Subscribers, Plans, Rates & Tariffs (docs.bill.run Product), Balances & Prepaid Includes, Lines and Tenant config. Services, discounts, charges, tax rates and billing cycles have been removed - see Current feature scope. For how official docs.bill.run terms map onto these resources, start with BillRun definitions → core-api.

Two pages are cross-cutting rather than per-domain, and are worth reading before adding anything new: Identity and deletion covers how every row is identified (UUID id primary keys, descriptive account_id/subscriber_id foreign keys) and what deletion means here (catalog and customer rows are soft-deleted via deleted_at, and reads filter it; append-only records such as audit logs and events have none). API conventions covers cross-cutting request/response shapes (list-endpoint pagination and its documented exceptions) that every domain's routes follow rather than re-deriving per resource.

For how users, credentials, sessions and roles work, see Identity and authentication. For task-oriented instructions, see Guides.