Skip to content

Project Structure

This document outlines the typical project structure generated by architect when creating a new application. The structure is designed to promote separation of concerns and align with Domain-Driven Design (DDD) principles.

The boilerplate for new applications is available as a Cookiecutter template on GitLab.

Generated Directory Tree

project_root/
├── app/
│   ├── __init__.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── deps.py
│   │   └── <version>/
│   │       ├── __init__.py # API version module
│   │       ├── dtos/
│   │       │   └── <dto_name>.py
│   │       └── routers/
│   │           └── <router_name>.py
│   ├── application/
│   │   ├── __init__.py
│   │   └── <bounded_ctx>/
│   │       ├── __init__.py # Bounded context application services
│   │       ├── commands/
│   │       │   └── <command_name>.py
│   │       ├── handlers/
│   │       │   ├── <handler_name>.py
│   │       │   └── <handler_permission_name>.py
│   │       ├── queries/
│   │       │   └── <query_name>.py
│   │       ├── sagas/
│   │       │   └── <domain_saga_orchestrator_name>.py
│   │       └── di.py
│   ├── config.py
│   ├── di.py
│   ├── domain/
│   │   ├── __init__.py
│   │   ├── <bounded_context_name>/
│   │   │   ├── __init__.py
│   │   │   ├── aggregates/
│   │   │   │   └── <domain_aggregate_name>.py
│   │   │   ├── events/
│   │   │   │   └── <domain_event_name>.py
│   │   │   ├── services/
│   │   │   │   └── <domain_service_name>.py
│   │   │   └── di.py
│   │   └── shared_kernel/
│   │       ├── __init__.py
│   │       ├── aggregates/
│   │       │   └── <shared_aggregate_name>.py
│   │       ├── events/
│   │       │   └── <shared_event_name>.py
│   │       ├── services/
│   │       │   └── <shared_service_name>.py
│   │       ├── sagas/
│   │       │   └── <shared_saga_orchestrator_name>.py
│   │       └── di.py
│   ├── infrastructure/
│   │   ├── __init__.py
│   │   ├── di.py
│   │   ├── <infrastructure_module_name>/
│   │   │   ├── __init__.py
│   │   │   └── <infra_service_name>.py
│   │   ├── messaging/
│   │   │   ├── __init__.py
│   │   │   ├── <event_consumer_name>.py
│   │   │   └── <event_publisher_name>.py
│   │   └── persistence/
│   │       ├── __init__.py
│   │       └── <bounded_context_name>/
│   │           ├── __init__.py
│   │           ├── models/
│   │           │   └── <model_name>.py
│   │           └── repositories/
│   │               └── <repo_name>.py
│   └── main.py
├── migrations/
├── tests/
│   └── ... (Project tests)
├── .env
├── .gitignore
├── pyproject.toml
└── README.md

Note on Placeholders: * <version>: Represents the API version (e.g., v1). * <bounded_context_name>: The name of a specific domain area (e.g., user_management, order_processing). * <dto_name>, <command_name>, etc.: Specific names for components, typically in snake_case (e.g., user_details_dto, create_order_command).

Key Directories Explained

  • app/: Contains the core application code.
    • app/api/: FastAPI routers, DTOs (Data Transfer Objects) for API requests/responses, and API-specific dependencies.
      • app/api/<version>/: Versioned API endpoints.
    • app/application/: Application services, command handlers, query handlers. Organized by bounded contexts.
      • app/application/<bounded_context_name>/sagas/: Saga orchestrators for managing long-running processes or distributed transactions within a bounded context.
    • app/domain/: Domain logic, including aggregates, domain events, domain services, and value objects.
      • app/domain/<bounded_context_name>/: Domain logic specific to a bounded context.
      • app/domain/shared_kernel/: Domain logic shared across multiple bounded contexts.
        • app/domain/shared_kernel/sagas/: Saga orchestrators that might coordinate across multiple bounded contexts or deal with shared concerns.
    • app/infrastructure/: Implementation details for external concerns like databases, message brokers, external APIs, etc.
      • app/infrastructure/persistence/: Database models (SQLModel) and repositories.
      • app/infrastructure/messaging/: Event consumers and publishers for asynchronous communication.
      • app/infrastructure/<infrastructure_module_name>/: Other infrastructure services (e.g., email, file storage, specific external API clients).
    • app/config.py: Application configuration settings (e.g., database URLs, API keys).
    • app/di.py: Root dependency injection container setup for the application.
    • app/main.py: FastAPI application instantiation and main entry point.
  • migrations/: Database migration scripts (typically managed by Alembic) to handle schema changes.
  • tests/: Unit, integration, and end-to-end tests for the application.
  • .env: Environment variables for local development (should not be committed to version control).
  • .gitignore: Specifies intentionally untracked files that Git should ignore.
  • pyproject.toml: Project metadata, dependencies (managed by uv or pip), and tool configurations (e.g., Ruff, Pytest).
  • README.md: Project overview, setup instructions, and other relevant information.

This structure provides a solid foundation for building scalable and maintainable applications. The cookiecutter template is available at https://gitlab.com/castlecraft/framework/architect. Use cruft instead of cookiecutter for help in upgrading boilerplate.