Architecture

This document outlines the architecture of the project, including the components, their responsibilities, and how they interact with each other.

Table of Contents

1. Project File Tree Structure
2. Top-Level Structure
3. Application Core (app/)
   • Core Configuration (app/core/config/)
   • Features (app/features/)
   • Main Application Entry (app/mainpy)
   • API Routers (app/routers/vX/)
4. Docs (docs/)
5. Scripts (scripts/)
6. Database Migrations (migrations/)
7. Containerization (dockerfiles/)
8. Testing (tests/)
9. Root-Level Configuration

Project File Tree Structure

Here's the detailed file tree structure of your project:

├── README.md
├── docs/
│   ├── errors.md
│   └── ...
├── scripts/
│   ├── error_generator.py
│   └── migrate.py
├── migrations/
│   ├── README
│   ├── __init__.py
│   ├── env.py
│   ├── script.py.mako
│   └── versions
│       └── ...
├── alembic.ini
├── app/
│   ├── __init__.py
│   ├── __main__.py
│   ├── core/
│   │   └── config/
│   │       └── ...
│   ├── features
│   │   ├── __init__.py
│   │   ├── feature-1/
│   │   │   ├── __init__.py
│   │   │   ├── exceptions.py
│   │   │   ├── model.py
│   │   │   ├── repository.py
│   │   │   └── service.py
│   │   ├── feature-2/
│   │   │   ├── __init__.py
│   │   │   ├── exceptions.py
│   │   │   ├── model.py
│   │   │   ├── repository.py
│   │   │   └── service.py
│   │   └── feature-3/
│   │       ├── __init__.py
│   │       ├── exceptions.py
│   │       ├── model.py
│   │       ├── repository.py
│   │       └── service.py
│   ├── main.py
│   └── routers/
│       ├── __init__.py
│       └── vX
│           ├── __init__.py
│           ├── feature_1/
│           │   ├── dependencies.py
│           │   ├── routes.py
│           │   └── schemas.py
│           ├── feature_2
│           │   ├── __init__.py
│           │   ├── dependencies.py
│           │   ├── routes.py
│           │   └── schemas.py
│           ├── feature_3
│           │   ├── __init__.py
│           │   ├── dependencies.py
│           │   ├── routes.py
│           │   └── schemas.py
│           └── ...
├── dev.compose.yml
├── dockerfiles
│   ├── migrate.Dockerfile
│   └── server.Dockerfile
├── env.py
├── isort.cfg
├── mypy.ini
├── poetry.lock
├── prod.compose.yml
├── pyproject.toml
├── pytest.ini
├── errors.json
└── tests
    ├── __init__.py
    ├── conftest.py
    └── features
        ├── __init__.py
        └── feature_1
            ├── vX
            │   ├── __init__.py
            │   ├── test_feature_1_integration.py
            │   ├── test_feature_1_service.py
            │   └── test_feature_1_repository.py
            └── ...

Top-Level Structure

The project is organized into several key directories:

• app/: Contains the core application logic.

• migrations/: Handles database migrations.

• dockerfiles/: Stores Docker configurations for various services.

• tests/: Holds all application tests.

• Root-level configuration files: Various configuration and project management files (pyproject.toml, poetry.lock, pytest.ini, alembic.ini, dev.compose.yml, prod.compose.yml, env.py, isort.cfg, mypy.ini, README.md).

Application Core (app/)

This is the heart of the application, encapsulating all business logic, data models, and API endpoints.

Core Configuration (app/core/config/)

This directory centralizes application-wide configurations, ensuring that environment-specific settings, database connections, and caching mechanisms are managed consistently.

• config/: This directory generally holds configuration files for various aspects of the application, such as database settings, cache configurations, auth configurations, server parameters, and many more. The ... indicates that specific configuration files (like redis.py, postgres.py, server.py) or directories would reside within this directory.

Features (app/features/)

This is where the domain logic for different functional areas (features) of the application resides. Each subdirectory represents a distinct feature with its own models, business logic, and data access. This promotes modularity, making it easier to develop, test, and maintain individual components.

• feature_1/, feature_2/, feature_3/: These represent distinct functional areas or modules within the application (e.g., users, products, orders).

Within each feature directory (e.g., feature_1), you'll typically find:

• model.py: Defines the SQLAlchemy ORM models, representing the data structures and relationships within the database.

• repository.py: Contains the data access logic, abstracting interactions with the database (e.g., CRUD operations for models). This layer decouples the business logic from the specifics of the database.

• service.py: Implements the core business logic for the feature. It orchestrates interactions between repositories, applies business rules, and performs operations related to the feature.

• exceptions.py: Defines custom exceptions specific to the feature, improving error handling and clarity.

The following diagram illustrates the interaction between the Routes, Services, and Repositories, along with their engagement with external services like databases and other APIs.

graph TD
    subgraph External Services
        DB[Database]
        API[External API]
    end

    subgraph Application
        Routes[API Routes]
        Services[Business Services]
        Repos[Data Repositories]
    end

    Routes --> Services
    Services --> Repos
    Repos --> DB
    Repos --> API

Main Application Entry (app/main.py)

This file typically serves as the main entry point for the FastAPI application, where routers are included, and the application instance is created.

API Routers (app/routers/vX/)

This directory structures the API endpoints for different versions of your API. vX indicates the version X. Each subdirectory within vX corresponds to a feature and defines its specific API routes.

Within each feature's router directory (e.g., feature-1):

• dependencies.py: Defines FastAPI dependency injection functions. These are reusable components for authentication, authorization, database sessions, or other prerequisites for routes.

• routes.py: Contains the actual FastAPI route definitions (API endpoints) for the feature. It handles HTTP requests and calls the appropriate service layer methods.

• schemas.py: Defines Pydantic models for request and response data validation, ensuring data integrity for API interactions.

Docs (docs/)

This directory contains documentation files for the project, including error codes, architecture diagrams, and other project-related information.

• errors.md: Contains a list of custom exceptions and their corresponding error codes. This document is generated automatically by using the error_generator.py script.

Scripts (scripts/)

This directory contains scripts that automate various tasks, such as generating error messages, running database migrations, or deploying the application.

• error_generator.py: Generates Python code with custom exceptions for errors specified in the errors.json file.

• migrate.py: Applies database migrations to the application. This script is used by the migrate.Dockerfile to apply migrations on startup. It is not really meant to be used directly.

Database Migrations (migrations/)

Alembic is used for database schema migrations. See Alembic for more information.

Containerization (dockerfiles/)

This directory holds Dockerfiles, which define how your application's services are built into Docker images for consistent deployment across different environments.

• server.Dockerfile: Defines the Docker image for your main application server.

• migrate.Dockerfile: Defines the Docker image for applying database migrations.

Testing (tests/)

This directory contains all automated tests for the application, ensuring code quality and functionality.

• conftest.py: Contains pytest fixtures and hooks that can be shared across multiple test files (e.g., setting up a test database, mock clients).

• vX/: Contains all test files for individual features or API endpoints within version X of your API.

  • feature_1/test_feature_1_integration.py: Test the interaction between the routes, services, and repositories for a specific feature.

  • feature_1/test_feature_1_service.py: Test the business logic for a specific feature.

  • feature_1/test_feature_1_repository.py: Test the data access logic for a specific feature.

Root-Level Configuration

These files manage project dependencies, code style, development environments, and other project-wide settings.

• alembic.ini: Configuration file for Alembic.
• dev.compose.yml: Docker Compose configuration for local development environments.
• env.py: Handles environment variable loading.
• isort.cfg: Configuration for isort, a tool to sort Python imports.
• mypy.ini: Configuration for mypy, a static type checker for Python.
• poetry.lock: Locks the exact versions of project dependencies.
• prod.compose.yml: Docker Compose configuration for production environments.
• pyproject.toml: Defines project metadata and dependencies (used by Poetry).
• pytest.ini: Configuration file for pytest, the testing framework.
• errors.json: List of custom exceptions and their corresponding error codes.
• README.md: Project documentation.