# jorge-martinez-gil/root-cause-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/jorge-martinez-gil/root-cause-analysis
- Repository: https://github.com/jorge-martinez-gil/root-cause-analysis

## Overview

This is an explainable transformer fault-diagnosis product: users provide measurements or use the sample fleet, then receive diagnoses with standards-based evidence and optional RDF/PROV-O output. The main route runs through the CLI and reasoning engine; separate branches support SPARQL screening and a compatibility classifier. The README documents these capabilities, while edges are limited to relationships shown in the sampled source or documented workflow.

Main entry points: [`src/root_cause_analysis/reasoning.py`](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/reasoning.py) (Diagnosis engine), [`src/root_cause_analysis/cli.py`](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/cli.py) (Command-line interface), [`src/root_cause_analysis/querying.py`](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/querying.py) (SPARQL screening), [`src/root_cause_analysis/ontology.py`](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/ontology.py) (Transformer ontology)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_sample_data["Sample measurements<br/>[datasets.py]"]
  node_classifier["Compatibility classifier<br/>[classification.py]"]
end

subgraph group_diagnosis["Diagnosis"]
  node_reasoning["Diagnosis engine<br/>[reasoning.py]"]
  node_diagnostic_rules["IEC and advisory rules<br/>[rules.py]"]
  node_diagnosis_result["Diagnosis and trace<br/>[reasoning.py]"]
  node_report["Markdown report<br/>[reasoning.py]"]
end

subgraph group_knowledge["Knowledge graph"]
  node_ontology["Transformer ontology<br/>[ontology.py]"]
  node_ontology_files["Ontology serializations"]
  node_knowledge_graph[("RDF knowledge graph<br/>[ontology.py]")]
  node_provenance["PROV-O provenance<br/>[reasoning.py]"]
end

subgraph group_screening["Screening"]
  node_querying["SPARQL screening<br/>[querying.py]"]
  node_screened_assets["Flagged assets<br/>[querying.py]"]
end

node_operator(("Operator"))
node_measurements["Measurement CSV"]

node_operator -->|"runs diagnosis"| node_cli
node_measurements -->|"supplies CSV"| node_cli
node_cli -->|"loads defaults"| node_sample_data
node_cli -->|"runs pipeline"| node_reasoning
node_reasoning -->|"evaluates rules"| node_diagnostic_rules
node_reasoning -->|"produces"| node_diagnosis_result
node_reasoning -->|"materializes graph"| node_ontology
node_reasoning -->|"records evidence"| node_provenance
node_reasoning -->|"formats results"| node_report
node_cli -->|"runs compatibility path"| node_classifier
node_ontology -->|"builds graph"| node_knowledge_graph
node_ontology -->|"serializes schema"| node_ontology_files
node_operator -->|"requests screening"| node_querying
node_cli -->|"screens assets"| node_querying
node_querying -->|"builds graph from measurements"| node_ontology
node_querying -->|"queries graph"| node_knowledge_graph
node_querying -->|"returns matches"| node_screened_assets

click node_cli "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/cli.py"
click node_sample_data "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/datasets.py"
click node_classifier "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/classification.py"
click node_reasoning "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/reasoning.py"
click node_diagnostic_rules "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/rules.py"
click node_diagnosis_result "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/reasoning.py"
click node_report "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/reasoning.py"
click node_ontology "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/ontology.py"
click node_ontology_files "https://github.com/jorge-martinez-gil/root-cause-analysis/tree/main/data/ontology"
click node_knowledge_graph "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/ontology.py"
click node_provenance "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/reasoning.py"
click node_querying "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/querying.py"
click node_screened_assets "https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/querying.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_cli,node_sample_data,node_classifier toneBlue
class node_reasoning,node_diagnostic_rules,node_diagnosis_result,node_report toneAmber
class node_ontology,node_ontology_files,node_knowledge_graph,node_provenance toneMint
class node_querying,node_screened_assets toneRose
class node_operator,node_measurements toneIndigo
```

## Components

### User entry

- [Command-line interface](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/cli.py): `src/root_cause_analysis/cli.py`
- [Sample measurements](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/datasets.py): `src/root_cause_analysis/datasets.py`
- [Compatibility classifier](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/classification.py): `src/root_cause_analysis/classification.py`

### Diagnosis

- [Diagnosis engine](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/reasoning.py): `src/root_cause_analysis/reasoning.py`
- [IEC and advisory rules](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/rules.py): `src/root_cause_analysis/rules.py`
- [Diagnosis and trace](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/reasoning.py): `src/root_cause_analysis/reasoning.py`
- [Markdown report](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/reasoning.py): `src/root_cause_analysis/reasoning.py`

### Knowledge graph

- [Transformer ontology](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/ontology.py): `src/root_cause_analysis/ontology.py`
- [Ontology serializations](https://github.com/jorge-martinez-gil/root-cause-analysis/tree/main/data/ontology): `data/ontology`
- [RDF knowledge graph](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/ontology.py): `src/root_cause_analysis/ontology.py`
- [PROV-O provenance](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/reasoning.py): `src/root_cause_analysis/reasoning.py`

### Screening

- [SPARQL screening](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/querying.py): `src/root_cause_analysis/querying.py`
- [Flagged assets](https://github.com/jorge-martinez-gil/root-cause-analysis/blob/main/src/root_cause_analysis/querying.py): `src/root_cause_analysis/querying.py`

### Other components

- **Operator**
- **Measurement CSV**

## Connections

- Operator → Command-line interface: runs diagnosis (evidence: `README.md`)
- Measurement CSV → Command-line interface: supplies CSV (evidence: `README.md`)
- Command-line interface → Sample measurements: loads defaults (evidence: `src/root_cause_analysis/cli.py`)
- Command-line interface → Diagnosis engine: runs pipeline (evidence: `src/root_cause_analysis/cli.py`)
- Diagnosis engine → IEC and advisory rules: evaluates rules (evidence: `src/root_cause_analysis/reasoning.py`)
- Diagnosis engine → Diagnosis and trace: produces (evidence: `src/root_cause_analysis/reasoning.py`)
- Diagnosis engine → Transformer ontology: materializes graph (evidence: `src/root_cause_analysis/reasoning.py`)
- Diagnosis engine → PROV-O provenance: records evidence (evidence: `src/root_cause_analysis/reasoning.py`)
- Diagnosis engine → Markdown report: formats results (evidence: `src/root_cause_analysis/reasoning.py`)
- Command-line interface → Compatibility classifier: runs compatibility path (evidence: `src/root_cause_analysis/cli.py`)
- Transformer ontology → RDF knowledge graph: builds graph (evidence: `src/root_cause_analysis/ontology.py`)
- Transformer ontology → Ontology serializations: serializes schema (evidence: `README.md`)
- Operator → SPARQL screening: requests screening (evidence: `README.md`)
- Command-line interface → SPARQL screening: screens assets (evidence: `src/root_cause_analysis/cli.py`)
- SPARQL screening → Transformer ontology: builds graph from measurements (evidence: `src/root_cause_analysis/querying.py`)
- SPARQL screening → RDF knowledge graph: queries graph (evidence: `src/root_cause_analysis/querying.py`)
- SPARQL screening → Flagged assets: returns matches (evidence: `src/root_cause_analysis/querying.py`)
