# eshwariwasankar/fairlens-data-science architecture

> Architecture diagram of the GitHub repository eshwariwasankar/fairlens-data-science, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eshwariwasankar/fairlens-data-science
- Repository: https://github.com/eshwariwasankar/fairlens-data-science

## Overview

FairLens is an interactive framework for auditing tabular classifiers for demographic bias, comparing mitigation strategies, and producing explanations and compliance reports. Its main workflow takes a bundled or uploaded dataset through cleaning and leakage-conscious preprocessing, trains and evaluates a baseline, measures subgroup fairness and proxy leakage, compares mitigations with statistical validation, then presents and exports results. The graph includes README-documented capabilities whose implementation was not sampled; their detailed internal call paths are therefore not inferred.

Main entry points: [`src/pipeline.py`](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/pipeline.py) (Audit pipeline), [`app.py`](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/app.py) (Streamlit dashboard), [`src/db/db_manager.py`](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/db/db_manager.py) (Experiment logging), [`src/config.py`](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/config.py) (Dataset configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Audit interface"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
  node_orchestrator["Audit pipeline<br/>[pipeline.py]"]
end

subgraph group_data["Data preparation"]
  node_settings["Dataset configuration<br/>[config.py]"]
  node_dataset_specs["Dataset definitions"]
  node_ingest["Dataset ingestion<br/>[loader.py]"]
  node_download["Benchmark downloader<br/>[downloader.py]"]
  node_clean["Data cleaning<br/>[cleaner.py]"]
  node_prepare["Split and preprocessing<br/>[preprocessor.py]"]
end

subgraph group_audit["Audit and mitigation"]
  node_eda["Exploratory analysis<br/>[eda.py]"]
  node_proxy["Proxy leakage analysis<br/>[proxy.py]"]
  node_trainer["Baseline training<br/>[trainer.py]"]
  node_evaluator["Predictive evaluation<br/>[evaluator.py]"]
  node_fairness["Fairness metrics<br/>[metrics.py]"]
  node_mitigators["Mitigation methods<br/>[mitigators.py]"]
  node_validation["Statistical validation<br/>[bootstrap.py]"]
end

subgraph group_explain["Explanation and reporting"]
  node_shap["SHAP explanations<br/>[shap_explainer.py]"]
  node_dice["DiCE recourse<br/>[dice_explainer.py]"]
  node_narrative["Audit narrative<br/>[insights.py]"]
  node_report["Report export<br/>[pdf_generator.py]"]
end

subgraph group_persistence["Experiment records"]
  node_database_api["Experiment logging<br/>[db_manager.py]"]
  node_database[("SQLite database<br/>[fairlens.db]")]
end

node_analyst(("Analyst"))

node_analyst -->|"uses"| node_dashboard
node_dashboard -->|"runs audit"| node_orchestrator
node_dashboard -->|"requests explanations"| node_shap
node_dashboard -->|"requests recourse"| node_dice
node_dashboard -->|"exports report"| node_report
node_dashboard -->|"loads records"| node_database_api
node_settings -->|"loads settings"| node_dataset_specs
node_orchestrator -->|"uses configuration"| node_settings
node_orchestrator -->|"loads dataset"| node_ingest
node_ingest -->|"downloads missing data"| node_download
node_orchestrator -->|"cleans data"| node_clean
node_orchestrator -->|"prepares splits"| node_prepare
node_orchestrator -->|"computes EDA"| node_eda
node_orchestrator -->|"ranks proxies"| node_proxy
node_orchestrator -->|"trains baseline"| node_trainer
node_orchestrator -->|"evaluates predictions"| node_evaluator
node_orchestrator -->|"measures fairness"| node_fairness
node_orchestrator -->|"compares mitigations"| node_mitigators
node_orchestrator -->|"bootstraps results"| node_validation
node_orchestrator -->|"computes importance"| node_shap
node_orchestrator -->|"generates recourse"| node_dice
node_orchestrator -->|"generates insights"| node_narrative
node_validation -->|"resamples metrics"| node_fairness
node_mitigators -->|"uses prepared data"| node_prepare
node_orchestrator -->|"logs metadata"| node_database_api
node_database_api -->|"reads and writes"| node_database
node_orchestrator -.->|"exports results"| node_report
node_orchestrator -.->|"logs audit results"| node_database_api

click node_dashboard "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/app.py"
click node_orchestrator "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/pipeline.py"
click node_settings "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/config.py"
click node_dataset_specs "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/dataset_config.yaml"
click node_ingest "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/data/loader.py"
click node_download "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/data/downloader.py"
click node_clean "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/data/cleaner.py"
click node_prepare "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/data/preprocessor.py"
click node_eda "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/analysis/eda.py"
click node_proxy "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/analysis/proxy.py"
click node_trainer "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/models/trainer.py"
click node_evaluator "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/models/evaluator.py"
click node_fairness "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/fairness/metrics.py"
click node_mitigators "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/fairness/mitigators.py"
click node_validation "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/fairness/bootstrap.py"
click node_shap "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/explainability/shap_explainer.py"
click node_dice "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/explainability/dice_explainer.py"
click node_narrative "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/explainability/insights.py"
click node_report "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/reporting/pdf_generator.py"
click node_database_api "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/db/db_manager.py"
click node_database "https://github.com/eshwariwasankar/fairlens-data-science/blob/main/data/fairlens.db"

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,node_orchestrator toneBlue
class node_settings,node_dataset_specs,node_ingest,node_download,node_clean,node_prepare toneAmber
class node_eda,node_proxy,node_trainer,node_evaluator,node_fairness,node_mitigators,node_validation toneMint
class node_shap,node_dice,node_narrative,node_report toneRose
class node_database_api,node_database,node_analyst toneIndigo
```

## Components

### Audit interface

- [Streamlit dashboard](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/app.py): `app.py`
- [Audit pipeline](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/pipeline.py): `src/pipeline.py`

### Data preparation

- [Dataset configuration](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/config.py): `src/config.py`
- [Dataset definitions](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/dataset_config.yaml): `dataset_config.yaml`
- [Dataset ingestion](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/data/loader.py): `src/data/loader.py`
- [Benchmark downloader](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/data/downloader.py): `src/data/downloader.py`
- [Data cleaning](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/data/cleaner.py): `src/data/cleaner.py`
- [Split and preprocessing](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/data/preprocessor.py): `src/data/preprocessor.py`

### Audit and mitigation

- [Exploratory analysis](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/analysis/eda.py): `src/analysis/eda.py`
- [Proxy leakage analysis](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/analysis/proxy.py): `src/analysis/proxy.py`
- [Baseline training](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/models/trainer.py): `src/models/trainer.py`
- [Predictive evaluation](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/models/evaluator.py): `src/models/evaluator.py`
- [Fairness metrics](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/fairness/metrics.py): `src/fairness/metrics.py`
- [Mitigation methods](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/fairness/mitigators.py): `src/fairness/mitigators.py`
- [Statistical validation](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/fairness/bootstrap.py): `src/fairness/bootstrap.py`

### Explanation and reporting

- [SHAP explanations](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/explainability/shap_explainer.py): `src/explainability/shap_explainer.py`
- [DiCE recourse](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/explainability/dice_explainer.py): `src/explainability/dice_explainer.py`
- [Audit narrative](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/explainability/insights.py): `src/explainability/insights.py`
- [Report export](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/reporting/pdf_generator.py): `src/reporting/pdf_generator.py`

### Experiment records

- [Experiment logging](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/src/db/db_manager.py): `src/db/db_manager.py`
- [SQLite database](https://github.com/eshwariwasankar/fairlens-data-science/blob/main/data/fairlens.db): `data/fairlens.db`

### Other components

- **Analyst**

## Connections

- Analyst → Streamlit dashboard: uses (evidence: `README.md`)
- Streamlit dashboard → Audit pipeline: runs audit (evidence: `app.py`)
- Streamlit dashboard → SHAP explanations: requests explanations (evidence: `app.py`)
- Streamlit dashboard → DiCE recourse: requests recourse (evidence: `app.py`)
- Streamlit dashboard → Report export: exports report (evidence: `app.py`)
- Streamlit dashboard → Experiment logging: loads records (evidence: `app.py`)
- Dataset configuration → Dataset definitions: loads settings (evidence: `src/config.py`)
- Audit pipeline → Dataset configuration: uses configuration (evidence: `src/pipeline.py`)
- Audit pipeline → Dataset ingestion: loads dataset (evidence: `src/pipeline.py`)
- Dataset ingestion → Benchmark downloader: downloads missing data (evidence: `src/data/loader.py`)
- Audit pipeline → Data cleaning: cleans data (evidence: `src/pipeline.py`)
- Audit pipeline → Split and preprocessing: prepares splits (evidence: `src/pipeline.py`)
- Audit pipeline → Exploratory analysis: computes EDA (evidence: `src/pipeline.py`)
- Audit pipeline → Proxy leakage analysis: ranks proxies (evidence: `src/pipeline.py`)
- Audit pipeline → Baseline training: trains baseline (evidence: `src/pipeline.py`)
- Audit pipeline → Predictive evaluation: evaluates predictions (evidence: `src/pipeline.py`)
- Audit pipeline → Fairness metrics: measures fairness (evidence: `src/pipeline.py`)
- Audit pipeline → Mitigation methods: compares mitigations (evidence: `src/pipeline.py`)
- Audit pipeline → Statistical validation: bootstraps results (evidence: `src/pipeline.py`)
- Audit pipeline → SHAP explanations: computes importance (evidence: `src/pipeline.py`)
- Audit pipeline → DiCE recourse: generates recourse (evidence: `src/pipeline.py`)
- Audit pipeline → Audit narrative: generates insights (evidence: `src/pipeline.py`)
- Statistical validation → Fairness metrics: resamples metrics (evidence: `src/fairness/bootstrap.py`)
- Mitigation methods → Split and preprocessing: uses prepared data (evidence: `src/fairness/mitigators.py`)
- Audit pipeline → Experiment logging: logs metadata (evidence: `src/pipeline.py`)
- Experiment logging → SQLite database: reads and writes (evidence: `src/db/db_manager.py`)
- Audit pipeline → Report export: exports results
- Audit pipeline → Experiment logging: logs audit results (evidence: `src/pipeline.py`)
