# arteria-project/arteria-delivery architecture

> Architecture diagram of the GitHub repository arteria-project/arteria-delivery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arteria-project/arteria-delivery
- Repository: https://github.com/arteria-project/arteria-delivery

## Overview

##### Main Components

- API Service (Tornado REST Service):
– Represented by the “delivery/app.py” file which is the entry point for the application.
– This component handles incoming RESTful API calls that clients will use.

- Request Handlers:
– Found under “delivery/handlers”, these modules (such as dds_handlers, delivery_handlers, project_handlers, etc.) implement the logic for different API endpoints.
– They serve as controllers processing user requests.

- Business/Service Layer:
– Under “delivery/services”, business logic such as analysing best practices, handling external programs, file system interactions, and staging work are implemented.
– This layer acts upon data provided or requested by the handlers before passing information further on.

- Data Access/Repository Layer:
– In “delivery/repositories”, access to persistence (e.g., creating, querying, and updating delivery records) is managed.
– This layer abstracts the database operations from the business logic.

- Database & Migration Management:
– The project uses Alembic (directory “alembic” and config files in “config/alembic.ini”) to handle schema migrations and database version control.
– Emphasize that schema changes made in “delivery/models/db_models.py” need migration scripts managed by Alembic.

- Configuration & Environment:
– The “config” directory contains configuration files for the application, logging, and organizational settings.
– There is also a Dockerfile for containerizing the service, indicating a deployment component.

- Testing:
– The “tests” folder (with unit and integration tests) shows how the components are verified separately, ensuring that the architecture’s separation is maintained.

##### Relationships and Interactions

- External Clients (or API Consumers) interact with the Tornado API (delivery/app.py).
- The API forwards requests to relevant Handlers.
- Handlers call the Service Layer to perform the core business functions.
- The Service Layer in turn uses the Repository Layer for CRUD operations against the database.
- The Repository Layer directly interacts with the database, where Alembic schedules and manages version updates and migrations.
- Configuration information feeds into the API service at startup, dictating log settings, DB connections, and other runtime parameters.
- The Dockerfile implies that containerization encapsulates the entire ecosystem for deployment.

##### Architectural Patterns and Design Principles

- Layered Architecture/MVC Patterns:
– The project cleanly separates concerns by splitting REST API (handlers), business logic (services), and data persistence (repositories).
– Database models are isolated in “delivery/models”.

- Configuration Management:
– System configuration is externalized in the “config” directory for easier modifications without code changes.

- Automated Database Migrations:
– Alembic is used for keeping the database schema in sync with the models.

- Testing and Continuous Integration:
– Integration and unit tests support each layer, ensuring interactions behave as expected.

##### Relevant Technologies and Tools

- Python 3.6+
- Tornado (as the underlying web server for handling REST APIs)
- Alembic for database migrations
- Docker for containerized deployment
- The layered structure is reflected in the use of repositories, services, and handlers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    subgraph "External Layer"
        EXT["External Clients"]:::external
    end

    %% API Layer
    subgraph "API Layer"
        API["API Service (/delivery/app.py)"]:::api
        CONFIG["Configuration (config)"]:::config
        DOCKER["Dockerfile"]:::docker
    end

    %% Request Layer
    subgraph "Request Layer"
        HANDLERS["Request Handlers (delivery/handlers)"]:::handlers
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        SERVICES["Service Layer (delivery/services)"]:::services
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        REPO["Repository Layer (delivery/repositories)"]:::repositories
    end

    %% Database Management
    subgraph "Database Management"
        DB["Database"]:::database
        ALEMBIC["Alembic & Migrations (alembic)"]:::alembic
        ALEMBIC_CONFIG["Alembic Config (config/alembic.ini)"]:::alembic_config
        DBMODELS["DB Models (delivery/models/db_models.py)"]:::models
    end

    %% Testing
    subgraph "Testing"
        TESTS["Tests (tests)"]:::tests
    end

    %% Connections / Data Flow
    EXT -->|"sendsRequest"| API
    API -->|"loads"| CONFIG
    API -->|"containerizedBy"| DOCKER
    API -->|"routesTo"| HANDLERS
    HANDLERS -->|"invokes"| SERVICES
    SERVICES -->|"calls"| REPO
    REPO -->|"performsCRUDOn"| DB
    DB -->|"schemaManagedBy"| ALEMBIC
    ALEMBIC_CONFIG -->|"configures"| ALEMBIC
    DBMODELS -->|"definesSchema"| DB

    %% Click Events
    click API "https://github.com/arteria-project/arteria-delivery/blob/master/delivery/app.py"
    click HANDLERS "https://github.com/arteria-project/arteria-delivery/tree/master/delivery/handlers"
    click SERVICES "https://github.com/arteria-project/arteria-delivery/tree/master/delivery/services"
    click REPO "https://github.com/arteria-project/arteria-delivery/tree/master/delivery/repositories"
    click ALEMBIC "https://github.com/arteria-project/arteria-delivery/tree/master/alembic"
    click DBMODELS "https://github.com/arteria-project/arteria-delivery/blob/master/delivery/models/db_models.py"
    click CONFIG "https://github.com/arteria-project/arteria-delivery/tree/master/config"
    click DOCKER "https://github.com/arteria-project/arteria-delivery/tree/master/Dockerfile"
    click TESTS "https://github.com/arteria-project/arteria-delivery/tree/master/tests"
    click ALEMBIC_CONFIG "https://github.com/arteria-project/arteria-delivery/blob/master/config/alembic.ini"

    %% Styling
    classDef external fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef api fill:#5DADE2,stroke:#154360,stroke-width:2px;
    classDef config fill:#D5DBDB,stroke:#566573,stroke-width:2px;
    classDef docker fill:#FAD7A0,stroke:#9A7D0A,stroke-width:2px;
    classDef handlers fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef services fill:#82E0AA,stroke:#196F3D,stroke-width:2px;
    classDef repositories fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef database fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef alembic fill:#F5CBA7,stroke:#7D6608,stroke-width:2px;
    classDef alembic_config fill:#FADBD8,stroke:#943126,stroke-width:2px;
    classDef models fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px;
    classDef tests fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
```
