Skip to content

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.