FastAPI backend¶

The backend is a FastAPI modular monolith. backend/app/main.py constructs the database, provider clients, controlled orchestrators, workflow seeds, application services, middleware, and mounted routers.

Startup lifecycle¶

create_app() performs these steps:

Load validated settings.
Construct provider clients.
Build the SQLAlchemy engine and session factory.
Create compatible local tables and migrations.
Seed active workflow templates.
Construct the eGovAI capability registry and orchestrator during lifespan.
Mount API routers under /api/v1.
Register consistent error handlers.
Close provider clients and dispose the database engine during shutdown.

Backend packages¶

Package	Responsibility
`api/`	FastAPI routers and dependencies
`schemas/`	Pydantic request, response, rule, and provider models
`models/`	SQLAlchemy persistence models
`repositories/`	Queries, ownership, and transaction boundaries
`services/`	Authentication, intent compilation, identity, vault, and access services
`domain/`	Deterministic journey, roadmap, dependency, and rule engines
`integrations/`	External provider clients, adapters, registry, and orchestration
`agents/`	Bounded journey-assistance tools and run metadata
`seeds/`	Versioned workflow definitions

Dependency injection¶

FastAPI dependencies open and close a SQLAlchemy session per request. Authentication dependencies resolve the bearer token into an AuthenticatedCitizen.

def get_db(request: Request):
    session = request.app.state.session_factory()
    try:
        yield session
    finally:
        session.close()

require_high_assurance builds on authentication and requires a current DOCUMENT_VAULT_ACCESS assurance record.

Controlled external capabilities¶

The ControlledApiOrchestrator accepts a capability code, not a caller-supplied URL. For each call it validates:

whether the capability exists and is enabled;
required permissions;
internal-only restrictions;
consent references;
current journey/action context;
idempotency keys;
Pydantic argument shape;
a per-capability in-memory rate limit; and
a timeout.

This prevents an AI response or API caller from turning the backend into an arbitrary HTTP proxy.

Persistence behavior¶

SQLite is the local default. SQLAlchemy 2 models and repositories also support a configured relational database URL. Workflow templates are versioned and seeded idempotently; existing personal journeys retain the workflow version used at creation.

Error handling¶

Expected failures raise EaktoError and return a safe error envelope. Unexpected exceptions are converted to a generic INTERNAL_SERVER_ERROR; exception details are not returned to the client.

See Error format.