# youcef3939/aletheia architecture

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

- Interactive diagram: https://gitdiagram.com/youcef3939/aletheia
- Repository: https://github.com/youcef3939/aletheia

## Overview

1. **Repository role**
   - This is a Python explainable-AI framework centered on **image model inference + attribution + visualization + metrics**.
   - The architecture is intentionally modular: the **dashboard** is separate from the **inference/explanation pipeline**, which is separate from the **model**, **explainer**, and **metrics** layers.

2. **Top-level control flow**
   - The main user flow is: **input image/sample → model prediction → explanation generation → metric computation → visualization/reporting**.
   - That flow is implemented twice: once for interactive use in the **Streamlit dashboard**, and once as a reusable programmatic entrypoint through **pipeline.py**.

3. **Dashboard boundary**
   - `dashboard/app.py` is the presentation layer.
   - It likely handles user interaction, sample selection/upload, display of predictions, and rendering of heatmaps/metrics.
   - Importantly, it should depend on the central pipeline rather than directly coupling to model or explainer internals.

4. **Orchestration layer**
   - `pipeline.py` is the central orchestrator and the best place to draw the “system spine” in an architecture diagram.
   - It coordinates loading a model, running inference, selecting an explainer, computing metrics, and preparing visual outputs for either the dashboard or external callers.

5. **Model subsystem**
   - `models/model_loader.py` encapsulates model loading and inference.
   - This is the boundary between the framework and the underlying deep learning model, likely a PyTorch model based on the README and Captum integration.
   - This layer should be treated as swappable: the framework is designed so different model weights/architectures can be plugged in without changing the rest of the stack.

6. **Explanation subsystem**
   - `explainers/captum_explainers.py` contains the attribution methods built on **Captum**.
   - This is where raw model inputs/gradients are turned into saliency or attribution maps.
   - In the diagram, this sits downstream of inference and upstream of visualization/metrics.

7. **Metrics subsystem**
   - `metrics/xai_metrics.py` computes explanation-quality metrics such as faithfulness/sensitivity-style evaluations mentioned in the README.
   - This layer consumes the model outputs and explanation artifacts, so it forms a separate analytical boundary from the explainer itself.
   - It is useful to show metrics as parallel to visualization, not embedded inside the UI.

8. **Visualization subsystem**
   - `utils/viz.py` is responsible for converting numeric outputs and attribution tensors into human-readable images, overlays, or plots.
   - It is the final presentation transform before results are shown in the dashboard or exported.
   - For architecture purposes, this is the bridge between analytic outputs and end-user interpretation.

9. **Cross-cutting concerns**
   - `utils/logger.py` provides logging for traceability and auditability.
   - `config.py` holds global settings such as paths, model/explainer selection, and runtime parameters.
   - These are cross-cutting support modules used by multiple layers rather than standalone subsystems.

10. **Extensibility model**
   - The repository is designed around replaceable components:
     - swap the model in `models/`
     - add attribution methods in `explainers/`
     - add evaluation methods in `metrics/`
     - adjust display logic in `utils/viz.py`
   - That means the key architectural boundary is the pipeline interface, not the dashboard itself.

11. **Runtime and packaging**
   - This is a **Python** project with a Streamlit frontend and ML/XAI dependencies listed in `requirements.txt`.
   - The runtime is therefore a local or server-side Python process that serves the dashboard and performs inference/explanation in-process, rather than calling out to external services.

12. **What to emphasize in a diagram**
   - Show one central pipeline feeding both:
     - the **dashboard UI**, and
     - the **programmatic API path**.
   - Around that core, show four main internal subsystems: **model loading/inference**, **Captum explainers**, **XAI metrics**, and **visualization**, with **config** and **logger** as shared support components.

Main entry points: [`pipeline.py`](https://github.com/youcef3939/aletheia/blob/main/pipeline.py) (Pipeline), [`metrics/xai_metrics.py`](https://github.com/youcef3939/aletheia/blob/main/metrics/xai_metrics.py) (Metrics), [`explainers/captum_explainers.py`](https://github.com/youcef3939/aletheia/blob/main/explainers/captum_explainers.py) (Explainers), [`config.py`](https://github.com/youcef3939/aletheia/blob/main/config.py) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_dashboard_app["Dashboard<br/>streamlit ui<br/>[app.py]"]
end

subgraph group_orchestration["Orchestration"]
  node_pipeline["Pipeline<br/>orchestrator<br/>[pipeline.py]"]
end

subgraph group_xai_core["XAI Core"]
  node_model_loader[("Model Loader<br/>inference boundary<br/>[model_loader.py]")]
  node_captum_explainers{{"Explainers<br/>attribution methods"}}
  node_xai_metrics["Metrics<br/>evaluation<br/>[xai_metrics.py]"]
  node_viz["Visualization<br/>rendering<br/>[viz.py]"]
end

subgraph group_support["Support"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_logger["Logger<br/>observability<br/>[logger.py]"]
end

node_dashboard_app -->|"uses"| node_pipeline
node_pipeline -->|"loads/infers"| node_model_loader
node_pipeline -->|"explains"| node_captum_explainers
node_pipeline -->|"evaluates"| node_xai_metrics
node_pipeline -->|"renders"| node_viz
node_pipeline -->|"reads"| node_config
node_pipeline -->|"logs"| node_logger
node_captum_explainers -->|"depends on"| node_model_loader
node_xai_metrics -->|"consumes"| node_model_loader
node_xai_metrics -->|"consumes"| node_captum_explainers
node_viz -->|"formats"| node_captum_explainers
node_viz -->|"formats"| node_xai_metrics
node_dashboard_app -->|"displays"| node_viz
node_config -->|"configures"| node_model_loader
node_config -->|"configures"| node_captum_explainers
node_config -->|"configures"| node_xai_metrics
node_logger -->|"shared"| node_dashboard_app

click node_dashboard_app "https://github.com/youcef3939/aletheia/blob/main/dashboard/app.py"
click node_pipeline "https://github.com/youcef3939/aletheia/blob/main/pipeline.py"
click node_model_loader "https://github.com/youcef3939/aletheia/blob/main/models/model_loader.py"
click node_captum_explainers "https://github.com/youcef3939/aletheia/blob/main/explainers/captum_explainers.py"
click node_xai_metrics "https://github.com/youcef3939/aletheia/blob/main/metrics/xai_metrics.py"
click node_viz "https://github.com/youcef3939/aletheia/blob/main/utils/viz.py"
click node_config "https://github.com/youcef3939/aletheia/blob/main/config.py"
click node_logger "https://github.com/youcef3939/aletheia/blob/main/utils/logger.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard_app toneBlue
class node_pipeline toneAmber
class node_model_loader,node_captum_explainers,node_xai_metrics,node_viz toneMint
class node_config,node_logger toneRose
```

## Components

### Presentation

Interactive user-facing dashboard

- [Dashboard](https://github.com/youcef3939/aletheia/blob/main/dashboard/app.py): streamlit ui · Interactive interface for loading samples, showing predictions, and rendering explanation outputs · `dashboard/app.py`

### Orchestration

Central runtime flow and API entrypoint

- [Pipeline](https://github.com/youcef3939/aletheia/blob/main/pipeline.py): orchestrator · Coordinates the end-to-end image inference, attribution, metrics, and output preparation flow · `pipeline.py`

### XAI Core

Model, explanation, metrics, and visualization subsystems

- [Model Loader](https://github.com/youcef3939/aletheia/blob/main/models/model_loader.py): inference boundary · Loads the underlying model and runs prediction/inference · `models/model_loader.py`
- [Explainers](https://github.com/youcef3939/aletheia/blob/main/explainers/captum_explainers.py): attribution methods · Captum-based explainers that turn model behavior into saliency or attribution maps · `explainers/captum_explainers.py`
- [Metrics](https://github.com/youcef3939/aletheia/blob/main/metrics/xai_metrics.py): evaluation · Computes explanation-quality metrics such as faithfulness and sensitivity-style scores · `metrics/xai_metrics.py`
- [Visualization](https://github.com/youcef3939/aletheia/blob/main/utils/viz.py): rendering · Converts numeric outputs and attribution tensors into plots, overlays, and human-readable artifacts · `utils/viz.py`

### Support

Shared configuration and logging

- [Config](https://github.com/youcef3939/aletheia/blob/main/config.py): settings · Global runtime settings for paths, model and explainer selection, and parameters · `config.py`
- [Logger](https://github.com/youcef3939/aletheia/blob/main/utils/logger.py): observability · Shared logging for traceability and debugging across the framework · `utils/logger.py`

## Connections

- Dashboard → Pipeline: uses · Dashboard delegates execution to the central pipeline rather than calling internals directly
- Pipeline → Model Loader: loads/infers · Pipeline loads the model and performs prediction
- Pipeline → Explainers: explains · Pipeline selects and runs attribution methods
- Pipeline → Metrics: evaluates · Pipeline computes explanation metrics from model outputs and attribution artifacts
- Pipeline → Visualization: renders · Pipeline prepares visual outputs for display or export
- Pipeline → Config: reads · Pipeline uses shared configuration for runtime behavior
- Pipeline → Logger: logs · Pipeline emits execution logs for traceability
- Explainers → Model Loader: depends on · Attribution methods operate on the loaded model and its gradients/outputs
- Metrics → Model Loader: consumes · Metrics use model predictions and related signals
- Metrics → Explainers: consumes · Metrics evaluate the generated explanation artifacts
- Visualization → Explainers: formats · Visualization turns attribution tensors into displayable artifacts
- Visualization → Metrics: formats · Visualization can present metric outputs in reports or UI
- Dashboard → Visualization: displays · Dashboard renders plots, overlays, and results produced by the visualization layer
- Config → Model Loader: configures · Settings influence model selection and load behavior
- Config → Explainers: configures · Settings influence explainer selection and runtime parameters
- Config → Metrics: configures · Settings influence metric selection and thresholds
- Logger → Dashboard: shared · Dashboard participates in the shared logging boundary
