# kaymansrinivasan/air-gapped-rca architecture

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

- Interactive diagram: https://gitdiagram.com/kaymansrinivasan/air-gapped-rca
- Repository: https://github.com/kaymansrinivasan/air-gapped-rca

## Overview

airgap-rca is a prototype for grounded root-cause analysis of wafer-sort failures on offline edge accelerators. Its intended engineer workflow starts with immutable tester logs, validates and chunks them with source-line provenance, retrieves similar historical evidence, drafts ranked possible causes with citations, and checks claims before answering or refusing. The sampled code implements synthetic data generation, validation, chunking, Chroma ingestion, case evidence retrieval, and local draft generation; the README describes verification as part of the proposed workflow. Some intended stages, including keyword search, are not represented by sampled implementation files.

Main entry points: [`src/retrieve_case_evidence.py`](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/retrieve_case_evidence.py) (Case Evidence Retrieval), [`src/chunk.py`](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/chunk.py) (Source-Line Chunker), [`src/generate.py`](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/generate.py) (Local Draft Generator), [`syn_data/product_a_v1/generate.py`](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/syn_data/product_a_v1/generate.py) (Wafer Log Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Synthetic Data"]
  node_loggen["Wafer Log Generator<br/>[generate.py]"]
  node_logs["Wafer Sort Logs"]
  node_validator["Dataset Validator<br/>[validate.py]"]
  node_scenarios["Case Histories"]
  node_scenario_builder["Scenario Builder"]
end

subgraph group_evidence["Evidence Preparation"]
  node_chunker["Source-Line Chunker<br/>[chunk.py]"]
  node_chunks["Observation Chunks"]
  node_ingest["Vector Ingestion<br/>[chroma_ingest.py]"]
  node_vector_store[("Local Chroma Store")]
end

subgraph group_retrieval["Case Retrieval"]
  node_query["Failure Query<br/>[observation.json]"]
  node_retriever["Case Evidence Retrieval"]
  node_evidence_bundle["Evidence Bundle"]
end

subgraph group_answer["Grounded Answer"]
  node_draft["Local Draft Generator<br/>[generate.py]"]
  node_ollama["Local Ollama"]
  node_verification["Citation Verification<br/>[verify.py]"]
  node_answer_result["Supported Answer / Refusal"]
end

node_engineer(("Engineer"))

node_loggen -->|"writes"| node_logs
node_loggen -->|"validates output"| node_validator
node_chunker -->|"independently validates"| node_validator
node_chunker -->|"reads source"| node_logs
node_chunker -->|"writes chunks"| node_chunks
node_scenario_builder -->|"reads observations"| node_chunks
node_scenario_builder -->|"writes records"| node_scenarios
node_ingest -->|"reads chunks"| node_chunks
node_ingest -->|"upserts vectors"| node_vector_store
node_engineer -.->|"supplies failure"| node_query
node_retriever -->|"loads query"| node_query
node_retriever -->|"loads histories"| node_scenarios
node_retriever -->|"queries candidates"| node_vector_store
node_retriever -.->|"creates evidence"| node_evidence_bundle
node_draft -->|"reads evidence"| node_evidence_bundle
node_draft -->|"requests draft"| node_ollama
node_draft -.->|"submits claims"| node_verification
node_verification -.->|"checks answer"| node_answer_result

click node_loggen "https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/syn_data/product_a_v1/generate.py"
click node_logs "https://github.com/kaymansrinivasan/air-gapped-rca/tree/main/syn_data/product_a_v1/logs"
click node_validator "https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/syn_data/product_a_v1/validate.py"
click node_scenarios "https://github.com/kaymansrinivasan/air-gapped-rca/tree/main/syn_data/product_a_scenarios_v1"
click node_scenario_builder "https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/scripts/create_product_a_scenarios.py"
click node_chunker "https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/chunk.py"
click node_ingest "https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/chroma_ingest.py"
click node_query "https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/syn_data/product_a_scenarios_v1/case_07/observation.json"
click node_retriever "https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/retrieve_case_evidence.py"
click node_draft "https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/generate.py"
click node_verification "https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/verify.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_loggen,node_logs,node_validator,node_scenarios,node_scenario_builder toneBlue
class node_chunker,node_chunks,node_ingest,node_vector_store toneAmber
class node_query,node_retriever,node_evidence_bundle toneMint
class node_draft,node_ollama,node_verification,node_answer_result toneRose
class node_engineer toneIndigo
```

## Components

### Synthetic Data

- [Wafer Log Generator](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/syn_data/product_a_v1/generate.py): `syn_data/product_a_v1/generate.py`
- [Wafer Sort Logs](https://github.com/kaymansrinivasan/air-gapped-rca/tree/main/syn_data/product_a_v1/logs): `syn_data/product_a_v1/logs`
- [Dataset Validator](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/syn_data/product_a_v1/validate.py): `syn_data/product_a_v1/validate.py`
- [Case Histories](https://github.com/kaymansrinivasan/air-gapped-rca/tree/main/syn_data/product_a_scenarios_v1): `syn_data/product_a_scenarios_v1`
- [Scenario Builder](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/scripts/create_product_a_scenarios.py): `scripts/create_product_a_scenarios.py`

### Evidence Preparation

- [Source-Line Chunker](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/chunk.py): `src/chunk.py`
- **Observation Chunks**
- [Vector Ingestion](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/chroma_ingest.py): `src/chroma_ingest.py`
- **Local Chroma Store**

### Case Retrieval

- [Failure Query](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/syn_data/product_a_scenarios_v1/case_07/observation.json): `syn_data/product_a_scenarios_v1/case_07/observation.json`
- [Case Evidence Retrieval](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/retrieve_case_evidence.py): `src/retrieve_case_evidence.py`
- **Evidence Bundle**

### Grounded Answer

- [Local Draft Generator](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/generate.py): `src/generate.py`
- **Local Ollama**
- [Citation Verification](https://github.com/kaymansrinivasan/air-gapped-rca/blob/main/src/verify.py): `src/verify.py`
- **Supported Answer / Refusal**

### Other components

- **Engineer**

## Connections

- Wafer Log Generator → Wafer Sort Logs: writes (evidence: `syn_data/product_a_v1/generate.py`)
- Wafer Log Generator → Dataset Validator: validates output (evidence: `syn_data/product_a_v1/generate.py`)
- Source-Line Chunker → Dataset Validator: independently validates (evidence: `src/chunk.py`)
- Source-Line Chunker → Wafer Sort Logs: reads source (evidence: `src/chunk.py`)
- Source-Line Chunker → Observation Chunks: writes chunks (evidence: `src/chunk.py`)
- Scenario Builder → Observation Chunks: reads observations (evidence: `scripts/create_product_a_scenarios.py`)
- Scenario Builder → Case Histories: writes records (evidence: `scripts/create_product_a_scenarios.py`)
- Vector Ingestion → Observation Chunks: reads chunks (evidence: `src/chroma_ingest.py`)
- Vector Ingestion → Local Chroma Store: upserts vectors (evidence: `src/chroma_ingest.py`)
- Engineer → Failure Query: supplies failure (evidence: `README.md`)
- Case Evidence Retrieval → Failure Query: loads query (evidence: `src/retrieve_case_evidence.py`)
- Case Evidence Retrieval → Case Histories: loads histories (evidence: `src/retrieve_case_evidence.py`)
- Case Evidence Retrieval → Local Chroma Store: queries candidates (evidence: `src/retrieve_case_evidence.py`)
- Case Evidence Retrieval → Evidence Bundle: creates evidence
- Local Draft Generator → Evidence Bundle: reads evidence (evidence: `src/generate.py`)
- Local Draft Generator → Local Ollama: requests draft (evidence: `src/generate.py`)
- Local Draft Generator → Citation Verification: submits claims (evidence: `README.md`)
- Citation Verification → Supported Answer / Refusal: checks answer (evidence: `README.md`)
