# danilbaibak/real-time-ml-prediction architecture

> Architecture diagram of the GitHub repository danilbaibak/real-time-ml-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danilbaibak/real-time-ml-prediction
- Repository: https://github.com/danilbaibak/real-time-ml-prediction

## Overview

##### Project type and purpose
- This is a backend‐only, RESTful Machine Learning service that exposes real‐time prediction endpoints.
- The README describes it as an example ML REST API covering model caching, asynchronous code, zero‐downtime pipeline updates, health checks, and separation of production vs. local environments.

##### File structure
Top‐level artifacts:
- docker/ & docker-compose-local.yml: contains Dockerfiles, bash init, Python requirements → containerized deployment
- Makefile: orchestration commands (init, up, restart, bash)
- src/: the application code
– server.py: entry point for FastAPI (or similar) REST API
– config.ini + logging.conf: configuration & logging
– models/: Pydantic schemas for request/response validation
– scripts/training.py: pipeline to train (and persist) an ML model
– sql/migrations/*.sql: Alembic-style migration scripts for pipeline_version and predictions tables
– utils/: helper modules (common functions, utilities)
– tests/: unit and integration test suites

##### README for additional insights
- It uses a Dockerized local environment.
- ML artifacts are saved under ml_pipelines (implied in container or volume)
- Exposes /health and /docs endpoints.
- Database stores training history and predictions.

a. Main components
1. API Layer (server.py)
- Exposes REST endpoints: /predict, /health, /docs
- Uses Pydantic models for input/output
2. Model Cache & Pipeline Loader
- In-memory (or external cache) to store the current ML pipeline
- Asynchronous reload endpoint or on-demand training triggers
3. ML Training Pipeline
- scripts/training.py reads data, fits model, serializes artifacts (ml_pipelines folder)
- Writes pipeline version to the database via migrations
4. Database (PostgreSQL)
- Tables: pipeline_version, predictions
- Manages metadata about model versions and persisted prediction logs
5. Docker / Container Orchestration
- Service container running the API + training scripts
- Database container
- docker-compose-local for local dev
6. External Clients
- Web or CLI clients calling /predict or /docs

b. Relationships & interactions
- Client → API Layer: HTTP calls (JSON in/out)
- API Layer → Model Cache: Fetches the loaded pipeline to compute predictions
- API Layer → Database:
– Reads latest pipeline_version for metadata/health
– Writes prediction results to predictions table
- ML Training Pipeline → Model Cache: Updates serialized artifacts on disk
- ML Training Pipeline → Database: Inserts new entry into pipeline_version
- Docker Compose: wires API container and DB container on a shared network

c. Architectural patterns & design principles
- Separation of concerns:
– server.py for routing, models/ for schema validation, utils/ for helper logic, scripts/ for data science pipeline
- Monolithic service with clear internal modules rather than microservices
- Asynchronous operation: training or reload can be invoked without blocking prediction requests
- Immutable artifacts: each pipeline version is uniquely tracked in the database
- Infrastructure as code: Dockerfiles, docker-compose, Makefile

d. Key technologies & libraries
- FastAPI (or Starlette) for REST endpoints and auto-generated Swagger (/docs)
- Pydantic for data validation (models/)
- Async Python (asyncio) for non-blocking operations
- SQL migrations (plain SQL under src/sql/migrations)
- Docker & docker-compose for containerization
- pytest or unittest for tests (src/tests/)

##### Essential elements to capture
- CI/CD: reference .github/workflows/linting.yml as a note for code quality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    direction TB

    Client["External Client"]:::external

    subgraph "Docker Container"
        direction TB
        APIServer["API Server"]:::compute
        click APIServer "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/src/server.py"
        Pydantic["Pydantic Models"]:::compute
        click Pydantic "https://github.com/danilbaibak/real-time-ml-prediction/tree/main/src/models/"
        Config["Config & Logging"]:::note
        click Config "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/src/config.ini"
        click Config "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/src/logging.conf"
        Cache["Model Cache & Pipeline Loader"]:::cache
        click Cache "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/src/utils/helpers.py"
        click Cache "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/src/utils/utils.py"
        Training["ML Training Pipeline"]:::compute
        click Training "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/src/scripts/training.py"
    end

    DB["PostgreSQL DB"]:::db
    click DB "https://github.com/danilbaibak/real-time-ml-prediction/tree/main/src/sql/migrations/"

    subgraph "Containerization"
        direction TB
        Dockfile["docker/Dockerfile"]:::note
        click Dockfile "https://github.com/danilbaibak/real-time-ml-prediction/tree/main/docker/Dockerfile"
        DockfileLocal["docker/Dockerfile-local"]:::note
        click DockfileLocal "https://github.com/danilbaibak/real-time-ml-prediction/tree/main/docker/Dockerfile-local"
        Requirements["docker/requirements.txt"]:::note
        click Requirements "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/docker/requirements.txt"
        Bashrc["docker/.bashrc"]:::note
        click Bashrc "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/docker/.bashrc"
        DockerCompose["docker-compose-local.yml"]:::note
        click DockerCompose "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/docker-compose-local.yml"
        MakefileN["Makefile"]:::note
        click MakefileN "https://github.com/danilbaibak/real-time-ml-prediction/tree/main/Makefile"
    end

    subgraph "Development & CI/CD"
        direction TB
        UnitTests["Unit Tests"]:::external
        click UnitTests "https://github.com/danilbaibak/real-time-ml-prediction/tree/main/src/tests/unit_tests/"
        IntegrationTests["Integration Tests"]:::external
        click IntegrationTests "https://github.com/danilbaibak/real-time-ml-prediction/tree/main/src/tests/integration_tests/"
        Linting["CI/CD Linting Workflow"]:::external
        click Linting "https://github.com/danilbaibak/real-time-ml-prediction/blob/main/.github/workflows/linting.yml"
    end

    Client -->|"/predict, /health, /docs"| APIServer
    APIServer -->|"Load/Invoke pipeline"| Cache
    APIServer -->|"Read/write metadata & predictions"| DB
    Training -->|"Serialize artifacts"| Cache
    Training -->|"INSERT pipeline_version"| DB

    classDef compute fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px
    classDef cache fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef note fill:#FFFACD,stroke:#333,stroke-width:1px
```
