System overview¶

eAkto uses a Flutter client, a FastAPI application, relational journey state, and controlled adapters for external government and storage services. The current implementation is a modular monolith, not a distributed microservice system.

High-level architecture¶

┌──────────────────────────────── Flutter ────────────────────────────────┐
│ Screens → Riverpod ApplicationController → EAktoRepository → Dio      │
│ Secure storage: eAkto session token + active journey identifier only   │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │ HTTPS / JSON / multipart
┌───────────────────────────────────▼─────────────────────────────────────┐
│ FastAPI routers                                                        │
│ auth · identity · intents · journeys · documents · journey agent       │
├─────────────────────────────────────────────────────────────────────────┤
│ Domain and application services                                        │
│ IntentCompiler · PersonalEngine · RoadmapService · DocumentVaultService│
├─────────────────────────────────────────────────────────────────────────┤
│ Repositories and SQLAlchemy models                                     │
│ users · sessions · intents · journeys · milestones · ownership         │
├─────────────────────────────────────────────────────────────────────────┤
│ ControlledApiOrchestrator + allowlisted adapters                        │
└───────────────┬──────────────┬─────────────┬───────────────┬────────────┘
                │              │             │               │
             eGovAI        eGovPH SSO     eVerify       Supabase Storage

Main responsibility boundaries¶

Layer	Owns	Does not own
Flutter presentation	Layout, interaction, local UI state, navigation	Provider secrets, workflow selection, official verification
Flutter repository	Typed HTTP call locations and multipart construction	Business rules
FastAPI routers	HTTP contract, dependencies, response models	Direct SQL details
Services/domain	Intent routing, assurance, journey resolution, evidence rules	UI rendering
Repositories	Queries and persistence	Provider HTTP calls
Integrations	Provider-specific transport and response validation	Citizen journey policy
Workflow seeds	Versioned declarative steps and content	Free-form executable code

Request path¶

For a typical journey:

Citizen message
  → POST /api/v1/intents/compile
  → validated situation assessment
  → compatible workflow code
  → POST /api/v1/journeys/from-intent/{intent_id}
  → rule/dependency resolution
  → persisted journey and milestones
  → GET /api/v1/journeys/{journey_id}/plan
  → Flutter renders backend-provided questions and documents

Trust boundaries¶

Device boundary — Flutter stores only the internal session token and active journey ID in secure storage.
Application boundary — FastAPI hashes session tokens before persistence and applies resource ownership checks.
High-assurance boundary — journey creation with document evidence and every vault route require a current high-assurance result.
Provider boundary — credentials are loaded from backend settings and never returned to Flutter.
AI boundary — generated content is validated and cannot supply arbitrary provider URLs, methods, headers, or capabilities.

Terminology

Older source names still use lifegraph and caseId. The active backend domain calls the persisted object a personal journey and exposes it under /journeys.