Concepts¶

The Apogee Framework is opinionated. Every project it generates follows the same architectural backbone, so a developer who knows one Apogee project knows them all.

Domain-Driven Design¶

Each generated project is divided into bounded contexts (one folder per context inside src/domain/). Inside each context you find:

Entity — the aggregate root, with business invariants enforced in __post_init__.
Value Objects — immutable, equality by value (Money, EmailAddress, etc.).
Repository port — interface in domain/; implementations live in infrastructure/.
Domain events — emitted by aggregates, handled by application services.

Clean Architecture¶

The dependency rule: outer layers depend on inner layers, never the reverse.

flowchart LR
    presentation -->|calls| application
    application  -->|uses ports| domain
    infrastructure -->|implements ports| domain
    presentation  -.->|wires| infrastructure

Layer	Responsibility	Knows about
`domain`	Pure business rules, no I/O	nothing external
`application`	Use cases, orchestration	domain only
`infrastructure`	DB, HTTP clients, brokers	domain (implements ports)
`presentation`	HTTP / CLI / queue handlers	application

SOLID¶

The CLI scaffolds code that respects:

Single Responsibility — each class has one reason to change.
Open/Closed — extend via dependency injection, not by modifying generated files.
Liskov — repository implementations are interchangeable.
Interface Segregation — narrow ports per use case.
Dependency Inversion — application/ depends only on abstractions.

Wiring is done by Dishka (DI container) — see src/presentation/container.py in any generated project.

Generative, not runtime-coupled¶

Generated projects do not depend on the apogee-framework repository at runtime. Generators emit plain Python that runs anywhere FastAPI runs.

The runtime base classes (Entities, ApiResponse, Alembic runner, …) live in apogee-core (separate package), which the generated project consumes as a normal pip dependency.

Everything in Docker¶

Generated projects ship with docker-compose.yml and Dockerfile.dev. The CLI exposes verbs that wrap docker-compose:

apogee up → docker-compose up -d
apogee logs → docker-compose logs -f app
apogee shell → docker-compose exec app bash
apogee migrate → runs Alembic inside the container

This means you do not install Postgres/MySQL/Mongo on your host — only Docker.