# aliprf/california_housing_explainable_prediction architecture

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

- Interactive diagram: https://gitdiagram.com/aliprf/california_housing_explainable_prediction
- Repository: https://github.com/aliprf/california_housing_explainable_prediction

## Overview

##### Main Components
a. CLI / Orchestration Layer
- Pixi runner (`pixi run train`, `pixi run explain`, `pixi run up`)
- Entrypoints: `main.py`, `ml/main.py`
b. Data & Model Pipeline
- Data Loader & Preprocessor (`ml/data_parser/data_parser.py`)
- Model Trainer & Predictor (`ml/model/random_forest_prediction.py`)
- Model Explainer (`ml/model/random_forest_explainer.py`)
- Schema Definitions (`ml/common/schemas/*.py`)
- Artifact Storage (trained model weights, evaluation data under `weights/`)
c. Server
- API & Routing (`server/server.py`)
- Configuration Loader (`config.py`)
d. Client (Web UI)
- Gradio (or similar) frontend (`client/client.py`)
e. External Users/Systems
- End users interacting via browser
- SHAP visualizations or downloaded reports

##### Relationships & Data Flows
- Training Flow (triggered via CLI):
[CLI] → loads `ml/data_parser` → passes processed data to `random_forest_prediction` → saves model & metrics.
- Explainer Flow (CLI):
[CLI] → loads saved model + test data → runs `random_forest_explainer` (SHAP) → outputs plots & feature‐importance.
- Serving Flow (run up):
[Server] ← configured by `config.py`
[Server] ↔ loads trained model artifacts
[Client/UI] ↔ [Server] via HTTP (Predictions & Explain requests)
[Server] → invokes ML modules (prediction or explainer) → returns JSON/HTML/images → [Client/UI] renders them

##### Architectural Patterns & Technologies
- Modular ML Pipeline: separation of data parsing, model training, and explainability.
- CLI‐driven orchestration: Pixi for environment & commands.
- Micro‐service‐like separation of server & client.
- Use of SHAP for interpretability.
- Python modules as “services” (e.g., `ml/data_parser`, `ml/model`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Offline Pipeline
    subgraph "Offline Pipeline"
        direction TB
        DataParser["Data Parser\n(ml/data_parser/data_parser.py)"]:::ml
        ModelTrainer["Model Trainer & Predictor\n(random_forest_prediction.py)"]:::ml
        ModelExplainer["Model Explainer\n(random_forest_explainer.py)"]:::ml
        Schema["Schema Definitions\n(california_housing_model.py)"]:::ml
    end

    %% Storage
    subgraph "Storage"
        direction TB
        Dataset[(California Housing Dataset)]:::storage
        ModelArtifacts[(Model Weights & Evaluation Data)]:::storage
    end

    %% CLI / Orchestration
    subgraph "CLI / Orchestration"
        direction TB
        PixiRunner["Pixi Runner\n(pixi run train/explain/up)"]:::cli
        CLIMain["main.py"]:::cli
        CLIMLMain["ml/main.py"]:::cli
    end

    %% Online Serving
    subgraph "Online Serving"
        direction TB
        User["End User (Browser)"]:::external
        Client["Web UI (Gradio)\n(client/client.py)"]:::ui
        Server["API & Routing\n(server/server.py)"]:::serve
        Config["Configuration Loader\n(config.py)"]:::serve
    end

    %% Offline Flow
    PixiRunner -->|"train/explain"| DataParser
    DataParser -->|"processed data"| ModelTrainer
    ModelTrainer -->|"save model & metrics"| ModelArtifacts
    ModelArtifacts -->|"load for explain"| ModelExplainer
    ModelArtifacts -->|"load for serving"| Server
    Schema -.-> DataParser

    %% CLI to Serving
    PixiRunner -->|"up"| Server

    %% Serving Flow
    User -->|uses UI| Client
    Client -->|"HTTP: predict/explain"| Server
    Server -->|"invoke prediction/explainer"| ModelTrainer
    Server -->|"invoke prediction/explainer"| ModelExplainer
    Server -->|"response JSON/HTML/images"| Client
    Client --> User

    %% Storage Relations
    Dataset -->|used by| DataParser

    %% Click Events
    click DataParser "https://github.com/aliprf/california_housing_explainable_prediction/blob/master/ml/data_parser/data_parser.py"
    click ModelTrainer "https://github.com/aliprf/california_housing_explainable_prediction/blob/master/ml/model/random_forest_prediction.py"
    click ModelExplainer "https://github.com/aliprf/california_housing_explainable_prediction/blob/master/ml/model/random_forest_explainer.py"
    click Schema "https://github.com/aliprf/california_housing_explainable_prediction/blob/master/ml/common/schemas/california_housing_model.py"
    click CLIMain "https://github.com/aliprf/california_housing_explainable_prediction/blob/master/main.py"
    click CLIMLMain "https://github.com/aliprf/california_housing_explainable_prediction/blob/master/ml/main.py"
    click Server "https://github.com/aliprf/california_housing_explainable_prediction/blob/master/server/server.py"
    click Config "https://github.com/aliprf/california_housing_explainable_prediction/blob/master/config.py"
    click Client "https://github.com/aliprf/california_housing_explainable_prediction/blob/master/client/client.py"

    %% Styles
    classDef ml fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef storage fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef cli fill:#cfd8dc,stroke:#455a64,color:#455a64
    classDef serve fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32
    classDef ui fill:#ffe082,stroke:#ff6f00,color:#ff6f00
    classDef external fill:#f0f4c3,stroke:#827717,color:#827717
```
