# department-for-transport-bods/bods architecture

> Architecture diagram of the GitHub repository department-for-transport-bods/bods, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/department-for-transport-bods/bods
- Repository: https://github.com/department-for-transport-bods/bods

## Overview

##### Main Components
- Source Code & Core Application: Represent the monolithic Django application (found in “transit_odp”) and list its major modules (API, AVLs, browsing, data quality, fares, notifications, ETL pipelines, etc.). This is the core business logic and service layer.
- CI/CD Pipeline: Indicate the integration of GitHub workflows (and the GitLab CI file) along with the pipelines that use “version.txt” for tagging releases. Show languages or build scripts (Makefile, pyproject.toml) and the ECR container registry where images are stored.
- Environments & Deployment Flow: Capture the multiple deployment stages – dev, test, uat, and prod – along with the “hotfix” process described in the README and the manual approval for prod deployments.
- External Integrations & Services: If present, mark integration points with external services such as the AWS infrastructure (ECR, possibly ECS or similar orchestration), third‐party notification delivery (e.g., Gov.UK Notify), or any external APIs the service may consume.

##### Relationships and Interactions
- Deployment Flow: Show how the Docker images are pulled from the registry and deployed across the different environments. From there, illustrate that traffic is handled by a reverse proxy (Nginx or Caddy) which routes user requests to the Django backend.
- Internal Communication: Within the application, note that API calls (e.g., those served by transit_odp/api) and inter-app communications (through Celery tasks, ETL worker processes, etc.) handle the core service operations. Data flows from external requests to the Django web server, then gets processed by background workers, with persistent storage via Postgres.

##### Architectural Patterns and Design Principles
- Containerization and Micro-deployment: Although the core application is monolithic in code, the deployment is split into logical services running in distinct containers.
- Separation of Concerns: The directory structure separates configuration (config/), CI-related files (ci/, .github/), and application logic (transit_odp/), ensuring that each aspect (web service, background tasks, ETL) is independently deployable or scalable.
- Automated CI/CD & Versioning: The pipelines are designed to ensure that branch merges trigger builds which are auto-deployed in non-prod environments and manually reviewed for prod, thereby enforcing stable release management.

##### Including Specific Technologies and Tools
- Backend: Django (with Gunicorn in prod), Celery for asynchronous task processing.
- Frontend: A collection of JavaScript (found in transit_odp/frontend/assets/js) and SASS stylesheets that support the user interface.
- Database: Postgres for persistent data storage.
- Container Tools: Docker with separate Dockerfiles for various services (Django, Nginx, Postgres, celery workers, etc.).
- CI/CD Tools: GitHub workflows and GitLab CI files, along with Docker Compose files for local/development configurations.
- Deployment Environment Integration: AWS ECR and deployment pipelines tied to branch/version management.
- Monitoring/Notifications: Modules for notifications and logging (e.g., using the configurations found in transit_odp/notifications).

- In the top section, indicate the developer workflow with branching and merge orders which lead through CI/CD.
- In the middle section, present the runtime architecture – containers (Django app, Nginx, Postgres, Celery workers) and their interdependencies.
- In the bottom section, show how external stakeholders (end-users, API consumers, the infrastructure team during prod deployments) interact with the system.

– Clearly labels each component and subcomponent.
– Incorporates annotations that describe deployment environments and CI/CD processes.

This detailed breakdown should allow any principal software engineer to understand and accurately map the architecture of this complex, multi-environment, containerised full-stack application.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Developer Workflow
    subgraph "Developer Workflow"
        DevWork["Developer Workstation"]:::developer
        Branch["Branching(feature->dev->test->main->prod)"]:::developer
        CICD["CI/CD Pipeline"]:::cicd
        Version["Versioning(version.txt)"]:::cicd
        DockerBuild["Docker Build Process"]:::cicd
        DevWork -->|"pushes changes"| Branch
        Branch -->|"triggers"| CICD
        CICD -->|"tags with"| Version
        CICD --> DockerBuild
    end

    Registry["Container Registry(AWS ECR)"]:::cicd
    DockerBuild --> Registry

    %% Deployment Environments
    subgraph "Deployment Environments"
        Dev["Dev"]:::container
        Test["Test"]:::container
        UAT["UAT"]:::container
        Prod["Prod(manual_approval)"]:::container
    end

    Registry --> Dev
    Registry --> Test
    Registry --> UAT
    Registry --> Prod

    %% Runtime Architecture - Deployment Flow
    Dev --> Proxy
    Test --> Proxy
    UAT --> Proxy
    Prod --> Proxy

    Proxy["Reverse Proxy(Nginx/Caddy)"]:::container
    Proxy --> DjangoContainer

    DjangoContainer["Django App Container(Gunicorn)"]:::container
    DjangoContainer --> CoreApp
    DjangoContainer --> FE
    DjangoContainer --> Celery
    DjangoContainer --> DB

    %% Core Django Application Subgraph
    subgraph "Core Django Application"
        Core["transit_odp(Core)"]:::app
        API["transit_odp/api"]:::app
        AVL["transit_odp/avl"]:::app
        DQ["transit_odp/data_quality"]:::app
        ETL["transit_odp/pipelines"]:::app
        Notif["transit_odp/notifications"]:::app
        Fares["transit_odp/fares"]:::app
        FaresVal["transit_odp/fares_validator"]:::app
        Tt["transit_odp/timetables"]:::app
        Browse["transit_odp/browse"]:::app

        Core --> API
        Core --> AVL
        Core --> DQ
        Core --> ETL
        Core --> Notif
        Core --> Fares
        Core --> FaresVal
        Core --> Tt
        Core --> Browse
    end

    %% Frontend Assets
    FE["Frontend Assets"]:::app

    %% Background Processing and Storage
    Celery["Celery Workers"]:::container
    DB["Postgres DB"]:::db

    %% External Integration
    NotifyExt["Gov.UK Notify"]:::external
    Notif -->|"sends notifications"| NotifyExt

    %% Containerization Infrastructure (Docker)
    DockerCfg["Docker Configurations(docker,docker/local,docker/production)"]:::container
    Compose["Docker Compose Files"]:::container
    CICD --> DockerCfg
    CICD --> Compose

    %% CI/CD Additional Scripts
    Github["GitHub Workflows(.github/workflows)"]:::cicd
    Gitlab["GitLab CI(.gitlab-ci.yml)"]:::cicd
    CIScripts["CI Scripts(ci/bods-ci.yml,Makefile,pyproject.toml)"]:::cicd
    CICD --> Github
    CICD --> Gitlab
    CICD --> CIScripts

    %% Environment Configuration
    Config["Environment Config(config/settings)"]:::cicd
    EnvTemp["Env Templates(.env.prod.template)"]:::cicd
    CoreApp --> Config
    Config --> EnvTemp

    %% Click Events for Component Mapping
    click Core "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp"
    click API "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/api"
    click AVL "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/avl"
    click DQ "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/data_quality"
    click ETL "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/pipelines"
    click Notif "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/notifications"
    click Fares "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/fares"
    click FaresVal "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/fares_validator"
    click Tt "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/timetables"
    click Browse "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/browse"
    click FE "https://github.com/department-for-transport-bods/bods/tree/dev/transit_odp/frontend/assets"
    click DockerCfg "https://github.com/department-for-transport-bods/bods/tree/dev/docker"
    click Github "https://github.com/department-for-transport-bods/bods/tree/dev/.github/workflows"
    click Gitlab "https://github.com/department-for-transport-bods/bods/blob/dev/.gitlab-ci.yml"
    click CIScripts "https://github.com/department-for-transport-bods/bods/blob/dev/ci/bods-ci.yml"
    click Config "https://github.com/department-for-transport-bods/bods/tree/dev/config/settings"
    click EnvTemp "https://github.com/department-for-transport-bods/bods/tree/dev/config"
    click Version "https://github.com/department-for-transport-bods/bods/blob/dev/version.txt"
    click Compose "https://github.com/department-for-transport-bods/bods/blob/dev/docker-compose.yml"

    %% Styles
    classDef developer fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef cicd fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef container fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef app fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef db fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
