Project structure¶

eAkto is a single repository with a Flutter client, a FastAPI server, tests, and this documentation site. The backend is a modular monolith: features are separated by Python packages while sharing one process and database.

eActo/
├── frontend/                 # Flutter application
│   ├── lib/
│   │   ├── core/             # Routing, theme, networking, shared services
│   │   └── features/         # Feature-first UI and state
│   ├── assets/               # Fonts, icons, and illustrations
│   └── test/                 # Widget and unit tests
├── backend/
│   ├── app/
│   │   ├── api/              # Routers mounted under /api/v1
│   │   ├── core/             # Configuration, security, shared policy
│   │   ├── models/           # SQLAlchemy persistence models
│   │   ├── schemas/          # Pydantic API contracts
│   │   ├── services/         # Application and provider integrations
│   │   └── workflows/        # Journey templates and execution logic
│   └── tests/                # API, service, and workflow tests
├── docs/                     # Markdown documentation
├── docs_theme/               # Custom eAkto MkDocs theme
├── mkdocs.yml                # Documentation navigation and build config
└── .env.example              # Safe configuration names and examples

Frontend boundaries¶

Flutter code is organized around user-facing features. A feature should own its screens, providers, models, and widgets when those elements are not broadly reusable. Cross-feature concerns belong in lib/core.

The frontend communicates with the backend through repositories and API clients. Screens should not assemble HTTP requests or persist access tokens directly.

Backend boundaries¶

The backend follows a request-to-service flow:

API router → schema validation → service/workflow → repository/model → response schema

• Routers translate HTTP into application calls.
• Schemas define validated input and output contracts.
• Services coordinate business rules and external systems.
• Workflow definitions describe questions, documents, milestones, and actions.
• Models persist users, identity assurance, intents, journeys, and documents.

Keep provider-specific payloads inside their adapter. The rest of eAkto should depend on an eAkto-owned interface.

Where new code belongs¶

Avoid adding code to legacy modules simply because a similar class exists there. Confirm that its router or feature is part of the currently mounted application first.