# ashgz8025/selfmend architecture

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

- Interactive diagram: https://gitdiagram.com/ashgz8025/selfmend
- Repository: https://github.com/ashgz8025/selfmend

## Overview

SelfMend is a data-quality monitoring and self-remediation system. Its main workflow accepts a batch, detects quality failures and drift, retrieves similar incidents, diagnoses the problem, checks diagnosis faithfulness and policy, then remediates or escalates. The API persists run traces and the dashboard presents them and can trigger runs. The graph preserves documented evaluation, fault injection, and ETL capabilities. Some links come from the SOURCE INDEX or README (the README is empty); unsampled modules are represented only where their role is clear, and uncertain wiring is omitted.

Main entry points: [`selfmend/agents/graph.py`](https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/graph.py) (Workflow Graph), [`selfmend/detection/detector.py`](https://github.com/ashgz8025/selfmend/blob/main/selfmend/detection/detector.py) (Unified Detector), [`selfmend/api/main.py`](https://github.com/ashgz8025/selfmend/blob/main/selfmend/api/main.py) (Run API), [`selfmend/evaluation/run_evaluation.py`](https://github.com/ashgz8025/selfmend/blob/main/selfmend/evaluation/run_evaluation.py) (Evaluation Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data Ingestion"]
  node_etl["Batch ETL<br/>[etl.py]"]
  node_faults["Fault Injection<br/>[injector.py]"]
  node_evaluation["Evaluation Runner<br/>[run_evaluation.py]"]
end

subgraph group_workflow["Diagnosis Workflow"]
  node_graph["Workflow Graph<br/>[graph.py]"]
  node_state["Pipeline State<br/>[state.py]"]
  node_detector_node["Detection Stage<br/>[nodes.py]"]
  node_detector["Unified Detector<br/>[detector.py]"]
  node_gx["GX Checks<br/>[gx_checks.py]"]
  node_drift["Drift Checks<br/>[drift_check.py]"]
  node_retriever["Incident Retrieval<br/>[nodes.py]"]
  node_diagnoser["Diagnosis Stage<br/>[nodes.py]"]
  node_faithfulness["Faithfulness Scoring<br/>[faithfulness.py]"]
  node_policy["Decision Gate<br/>[gate.py]"]
end

subgraph group_repair["Remediation"]
  node_executor["Repair Executor<br/>[executor.py]"]
  node_actions["Repair Actions<br/>[actions.py]"]
end

subgraph group_interfaces["Interfaces"]
  node_api["Run API<br/>[main.py]"]
  node_dashboard["Dashboard<br/>[app.py]"]
end

subgraph group_records["Persistence"]
  node_incident_store[("Incident Memory<br/>[incident_store.py]")]
  node_db_session["DB Sessions<br/>[session.py]"]
  node_db_models["Audit Models<br/>[models.py]"]
end

node_user(("Operator"))

node_user -->|"operates"| node_dashboard
node_dashboard -->|"fetches runs"| node_api
node_dashboard -->|"injects faults"| node_faults
node_api -->|"runs workflow"| node_graph
node_api -->|"injects faults"| node_faults
node_graph -->|"dispatches stages"| node_detector_node
node_graph -->|"dispatches stages"| node_retriever
node_graph -->|"dispatches stages"| node_diagnoser
node_graph -->|"dispatches stages"| node_policy
node_graph -->|"dispatches repair"| node_executor
node_detector_node -->|"calls detection"| node_detector
node_detector -->|"runs checks"| node_gx
node_detector -->|"runs checks"| node_drift
node_retriever -->|"retrieves incidents"| node_incident_store
node_diagnoser -->|"uses retrieved evidence"| node_incident_store
node_diagnoser -->|"scores diagnosis"| node_faithfulness
node_executor -->|"applies action"| node_actions
node_executor -->|"revalidates batch"| node_detector
node_api -->|"persists run"| node_db_session
node_db_session -->|"creates schema"| node_db_models
node_evaluation -->|"injects faults"| node_faults
node_evaluation -->|"evaluates detection"| node_detector
node_evaluation -->|"evaluates workflow"| node_graph

click node_etl "https://github.com/ashgz8025/selfmend/blob/main/selfmend/pipeline/etl.py"
click node_faults "https://github.com/ashgz8025/selfmend/blob/main/selfmend/faults/injector.py"
click node_api "https://github.com/ashgz8025/selfmend/blob/main/selfmend/api/main.py"
click node_dashboard "https://github.com/ashgz8025/selfmend/blob/main/selfmend/dashboard/app.py"
click node_graph "https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/graph.py"
click node_state "https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/state.py"
click node_detector_node "https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/nodes.py"
click node_detector "https://github.com/ashgz8025/selfmend/blob/main/selfmend/detection/detector.py"
click node_gx "https://github.com/ashgz8025/selfmend/blob/main/selfmend/detection/gx_checks.py"
click node_drift "https://github.com/ashgz8025/selfmend/blob/main/selfmend/detection/drift_check.py"
click node_retriever "https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/nodes.py"
click node_incident_store "https://github.com/ashgz8025/selfmend/blob/main/selfmend/memory/incident_store.py"
click node_diagnoser "https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/nodes.py"
click node_faithfulness "https://github.com/ashgz8025/selfmend/blob/main/selfmend/trust/faithfulness.py"
click node_policy "https://github.com/ashgz8025/selfmend/blob/main/selfmend/policy/gate.py"
click node_executor "https://github.com/ashgz8025/selfmend/blob/main/selfmend/remediation/executor.py"
click node_actions "https://github.com/ashgz8025/selfmend/blob/main/selfmend/remediation/actions.py"
click node_db_session "https://github.com/ashgz8025/selfmend/blob/main/selfmend/db/session.py"
click node_db_models "https://github.com/ashgz8025/selfmend/blob/main/selfmend/db/models.py"
click node_evaluation "https://github.com/ashgz8025/selfmend/blob/main/selfmend/evaluation/run_evaluation.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_etl,node_faults,node_evaluation toneBlue
class node_graph,node_state,node_detector_node,node_detector,node_gx,node_drift,node_retriever,node_diagnoser,node_faithfulness,node_policy toneAmber
class node_executor,node_actions toneMint
class node_api,node_dashboard toneRose
class node_incident_store,node_db_session,node_db_models,node_user toneIndigo
```

## Components

### Data Ingestion

- [Batch ETL](https://github.com/ashgz8025/selfmend/blob/main/selfmend/pipeline/etl.py): `selfmend/pipeline/etl.py`
- [Fault Injection](https://github.com/ashgz8025/selfmend/blob/main/selfmend/faults/injector.py): `selfmend/faults/injector.py`
- [Evaluation Runner](https://github.com/ashgz8025/selfmend/blob/main/selfmend/evaluation/run_evaluation.py): `selfmend/evaluation/run_evaluation.py`

### Diagnosis Workflow

- [Workflow Graph](https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/graph.py): `selfmend/agents/graph.py`
- [Pipeline State](https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/state.py): `selfmend/agents/state.py`
- [Detection Stage](https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/nodes.py): `selfmend/agents/nodes.py`
- [Unified Detector](https://github.com/ashgz8025/selfmend/blob/main/selfmend/detection/detector.py): `selfmend/detection/detector.py`
- [GX Checks](https://github.com/ashgz8025/selfmend/blob/main/selfmend/detection/gx_checks.py): `selfmend/detection/gx_checks.py`
- [Drift Checks](https://github.com/ashgz8025/selfmend/blob/main/selfmend/detection/drift_check.py): `selfmend/detection/drift_check.py`
- [Incident Retrieval](https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/nodes.py): `selfmend/agents/nodes.py`
- [Diagnosis Stage](https://github.com/ashgz8025/selfmend/blob/main/selfmend/agents/nodes.py): `selfmend/agents/nodes.py`
- [Faithfulness Scoring](https://github.com/ashgz8025/selfmend/blob/main/selfmend/trust/faithfulness.py): `selfmend/trust/faithfulness.py`
- [Decision Gate](https://github.com/ashgz8025/selfmend/blob/main/selfmend/policy/gate.py): `selfmend/policy/gate.py`

### Remediation

- [Repair Executor](https://github.com/ashgz8025/selfmend/blob/main/selfmend/remediation/executor.py): `selfmend/remediation/executor.py`
- [Repair Actions](https://github.com/ashgz8025/selfmend/blob/main/selfmend/remediation/actions.py): `selfmend/remediation/actions.py`

### Interfaces

- [Run API](https://github.com/ashgz8025/selfmend/blob/main/selfmend/api/main.py): `selfmend/api/main.py`
- [Dashboard](https://github.com/ashgz8025/selfmend/blob/main/selfmend/dashboard/app.py): `selfmend/dashboard/app.py`

### Persistence

- [Incident Memory](https://github.com/ashgz8025/selfmend/blob/main/selfmend/memory/incident_store.py): `selfmend/memory/incident_store.py`
- [DB Sessions](https://github.com/ashgz8025/selfmend/blob/main/selfmend/db/session.py): `selfmend/db/session.py`
- [Audit Models](https://github.com/ashgz8025/selfmend/blob/main/selfmend/db/models.py): `selfmend/db/models.py`

### Other components

- **Operator**

## Connections

- Operator → Dashboard: operates (evidence: `selfmend/dashboard/app.py`)
- Dashboard → Run API: fetches runs (evidence: `selfmend/dashboard/app.py`)
- Dashboard → Fault Injection: injects faults (evidence: `selfmend/dashboard/app.py`)
- Run API → Workflow Graph: runs workflow (evidence: `selfmend/api/main.py`)
- Run API → Fault Injection: injects faults (evidence: `selfmend/api/main.py`)
- Workflow Graph → Detection Stage: dispatches stages (evidence: `selfmend/agents/graph.py`)
- Workflow Graph → Incident Retrieval: dispatches stages (evidence: `selfmend/agents/graph.py`)
- Workflow Graph → Diagnosis Stage: dispatches stages (evidence: `selfmend/agents/graph.py`)
- Workflow Graph → Decision Gate: dispatches stages (evidence: `selfmend/agents/graph.py`)
- Workflow Graph → Repair Executor: dispatches repair (evidence: `selfmend/agents/graph.py`)
- Detection Stage → Unified Detector: calls detection (evidence: `selfmend/agents/nodes.py`)
- Unified Detector → GX Checks: runs checks (evidence: `selfmend/detection/detector.py`)
- Unified Detector → Drift Checks: runs checks (evidence: `selfmend/detection/detector.py`)
- Incident Retrieval → Incident Memory: retrieves incidents (evidence: `selfmend/agents/nodes.py`)
- Diagnosis Stage → Incident Memory: uses retrieved evidence (evidence: `selfmend/agents/nodes.py`)
- Diagnosis Stage → Faithfulness Scoring: scores diagnosis (evidence: `selfmend/agents/nodes.py`)
- Repair Executor → Repair Actions: applies action (evidence: `selfmend/remediation/executor.py`)
- Repair Executor → Unified Detector: revalidates batch (evidence: `selfmend/remediation/executor.py`)
- Run API → DB Sessions: persists run (evidence: `selfmend/api/main.py`)
- DB Sessions → Audit Models: creates schema (evidence: `selfmend/db/session.py`)
- Evaluation Runner → Fault Injection: injects faults (evidence: `selfmend/evaluation/run_evaluation.py`)
- Evaluation Runner → Unified Detector: evaluates detection (evidence: `selfmend/evaluation/run_evaluation.py`)
- Evaluation Runner → Workflow Graph: evaluates workflow (evidence: `selfmend/evaluation/run_evaluation.py`)
