> ## Documentation Index
> Fetch the complete documentation index at: https://freelance-4888ed08.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical Architecture

> Microservices design, component ecosystem, and data flow

Engineering

> [!NOTE]
>
> **What this does:** Details the microservices architecture — how the ML training layer, orchestration engine, and serving API are decoupled for independent scaling and deployment.

The system adopts a **microservices-oriented architecture**, explicitly decoupling the computation layer (Machine Learning) from the presentation layer (User Interface).

## High-Level Design

The architecture strictly separates the **Kedro**-based training pipelines, the **Airflow** orchestrator, and the **FastAPI** model serving layer.

```mermaid theme={null}
graph TD
    %% Styling
    classDef person fill:#4F46E5,stroke:#fff,color:#fff,stroke-width:2px;
    classDef ui fill:#E0E7FF,stroke:#4338ca,color:#1e1b4b,stroke-width:2px;
    classDef orchestrator fill:#FEF3C7,stroke:#b45309,color:#78350f,stroke-width:2px;
    classDef ml fill:#DCFCE7,stroke:#15803d,color:#14532d,stroke-width:2px;
    
    %% Actors
    User([Business Planner]):::person
    
    %% Demand Forecasting System
    subgraph "Demand Forecasting System"
        direction TB
        
        %% Components
        UI[UI Dashboard<br/><i>Plotly Dash</i>]:::ui
        Airflow[Airflow Orchestrator<br/><i>Batch Scheduler</i>]:::orchestrator
        
        subgraph "ML Core"
        Pipeline[Kedro Pipeline<br/><i>Training & Inference</i>]:::ml
            Artifacts[(S3 Artifacts<br/><i>Models & Data</i>)]:::ml
            DB[(PostgreSQL<br/><i>Forecasts & Metadata</i>)]:::ml
        end
    end

    %% Flow
    User -->|Views Forecasts| UI
    User -->|Triggers Run| Airflow
    
    Airflow -->|Orchestrates| Pipeline
    Pipeline -->|Reads/Writes| Artifacts
    Pipeline -->|Saves Metadata| DB
    
    UI -->|Reads Parquet| Artifacts
    
    %% Link Styling
    linkStyle default stroke:#6366f1,stroke-width:2px;
```

## Component Ecosystem

**1. ML Service (app-ml)**

The computational core powered by **FastAPI** and **Kedro**.

* **Role**: Exposes high-performance REST endpoints for inference and training triggers.
* **Pipeline Engine**: Uses **Kedro** to orchestrate modular, reproducible data transformations and model training nodes.
* **Model**: **CatBoost** regressor optimized with **Optuna**.
* **Port**: `8000` (Inference), `8001` (Metrics)

**2. Orchestration (Airflow)**

The heartbeat of the MLOps lifecycle.

* **Role**: Schedules and monitors recurring jobs (e.g., "Weekly Retraining", "Daily Batch Inference").
* **Integration**: Triggers Kedro nodes directly via the **Airflow TaskFlow API**, enabling granular observability.
* **Observability**: Provides a UI for tracking DAG success/failure and retrying halted pipelines.

**3. Experiment Tracking (MLflow)**

The centralized model registry and experiment logger.

* **Role**: Tracks every training run, logging hyperparameters (`learning_rate`, `depth`), metrics (`RMSE`), and artifacts (`model.pickle`).
* **Registry**: Promotes the best performing models to "Staging" or "Production" for the API to consume.

**4. UI Dashboard (app-ui)**

The interactive presentation layer for business planners.

* **Tech Stack**: **Dash** (Plotly) + **Dash Bootstrap Components**.
* **Behavior**: Stateless frontend that reads processed Parquet files directly from the shared volume/S3 for the latest forecasts.
* **Port**: `8050`

## Infrastructure

> [card] Shared Library (common)
>
> Enforces consistency by providing unified `read_config` and `data_manager` modules used by both training and inference.

> [card] PostgreSQL
>
> Persists forecast results, metadata, and Optuna study history for long-term storage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.