# meenalgada142/waveeye architecture

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

- Interactive diagram: https://gitdiagram.com/meenalgada142/waveeye
- Repository: https://github.com/meenalgada142/waveeye

## Overview

WaveEye is an offline RTL debugging tool for diagnosing AXI4-Lite protocol failures from SystemVerilog and VCD inputs. Its documented workflow converts waveforms into cycle data, builds an RTL intermediate representation, checks protocol and structural/temporal behavior, then backtracks from violations to produce a causal verdict and evidence-rich reports. The graph preserves those documented stages and capability branches. Several subsystem links are based on the README’s stage diagram; unsampled implementation details are not asserted beyond that documentation.

Main entry points: [`IR_backtracking/ir_builder.py`](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/ir_builder.py) (RTL intermediate records), [`IR_backtracking/protocols/axi_lite/adapter.py`](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/protocols/axi_lite/adapter.py) (AXI-Lite rules), [`IR_backtracking/rca_resolver.py`](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_resolver.py) (Root cause resolution), [`IR_backtracking/rca_core/io.py`](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/io.py) (Waveform data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Input and preprocessing"]
  node_app["Interactive entry<br/>[main.py]"]
  node_vcdprep["VCD preprocessing"]
  node_rtlprep["RTL preprocessing"]
  node_waveform["Waveform data<br/>[io.py]"]
end

subgraph group_analysis["RTL and protocol analysis"]
  node_ir["RTL intermediate records<br/>[ir_builder.py]"]
  node_aliases["Signal aliases<br/>[alias_engine.py]"]
  node_protocol["AXI-Lite rules<br/>[adapter.py]"]
  node_signalmap["Signal grouping<br/>[signal_map.py]"]
  node_datapath["Datapath semantics"]
  node_memory["Memory write checks"]
  node_temporal["FSM and temporal checks"]
end

subgraph group_causality["Root cause analysis"]
  node_contracts["Causal obligations<br/>[contracts.py]"]
  node_engine["RCA core engine<br/>[engine.py]"]
  node_backtrack["Predicate backtracking"]
  node_causalgraph["Causal graph<br/>[causal_graph.py]"]
  node_resolver["Root cause resolution<br/>[rca_resolver.py]"]
end

subgraph group_reporting["Verdicts and reports"]
  node_diagnosis["Diagnosis report"]
  node_reports["Proof and analysis reports"]
  node_outputs["Analysis output files"]
end

node_engineer(("Engineer"))

node_engineer -->|"provides inputs"| node_app
node_app -.->|"starts analysis"| node_vcdprep
node_vcdprep -->|"converts VCD"| node_waveform
node_rtlprep -->|"parses RTL"| node_ir
node_ir -->|"resolves aliases"| node_aliases
node_ir -->|"checks handshakes"| node_protocol
node_protocol -->|"groups signals"| node_signalmap
node_ir -->|"checks mappings"| node_datapath
node_ir -->|"checks writes"| node_memory
node_waveform -->|"supplies cycles"| node_protocol
node_waveform -->|"supplies traces"| node_temporal
node_protocol -.->|"defines obligations"| node_contracts
node_contracts -->|"evaluates"| node_engine
node_engine -->|"backtracks predicates"| node_backtrack
node_engine -->|"builds dependencies"| node_causalgraph
node_datapath -.->|"informs verdict"| node_resolver
node_backtrack -.->|"supports cause"| node_resolver
node_causalgraph -.->|"supports cause"| node_resolver
node_resolver -.->|"renders verdict"| node_diagnosis
node_diagnosis -->|"details evidence"| node_reports
node_reports -->|"writes reports"| node_outputs
node_outputs -->|"returns findings"| node_engineer

click node_app "https://github.com/meenalgada142/waveeye/blob/main/main.py"
click node_vcdprep "https://github.com/meenalgada142/waveeye/tree/main/Preprocessing/vcd"
click node_rtlprep "https://github.com/meenalgada142/waveeye/tree/main/Preprocessing/rtl"
click node_waveform "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/io.py"
click node_ir "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/ir_builder.py"
click node_aliases "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/alias_engine.py"
click node_protocol "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/protocols/axi_lite/adapter.py"
click node_signalmap "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/protocols/axi_lite/signal_map.py"
click node_datapath "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/semantic_datapath_analysis.py"
click node_memory "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/semantic_checks/memory_write_analysis.py"
click node_temporal "https://github.com/meenalgada142/waveeye/tree/main/IR_backtracking"
click node_contracts "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/contracts.py"
click node_engine "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/engine.py"
click node_backtrack "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/predicate_backtrack.py"
click node_causalgraph "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/causal_graph.py"
click node_resolver "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_resolver.py"
click node_diagnosis "https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/reports/console_diagnosis.py"
click node_reports "https://github.com/meenalgada142/waveeye/tree/main/IR_backtracking/reports"

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_app,node_vcdprep,node_rtlprep,node_waveform toneBlue
class node_ir,node_aliases,node_protocol,node_signalmap,node_datapath,node_memory,node_temporal toneAmber
class node_contracts,node_engine,node_backtrack,node_causalgraph,node_resolver toneMint
class node_diagnosis,node_reports,node_outputs toneRose
class node_engineer toneIndigo
```

## Components

### Input and preprocessing

- [Interactive entry](https://github.com/meenalgada142/waveeye/blob/main/main.py): `main.py`
- [VCD preprocessing](https://github.com/meenalgada142/waveeye/tree/main/Preprocessing/vcd): `Preprocessing/vcd`
- [RTL preprocessing](https://github.com/meenalgada142/waveeye/tree/main/Preprocessing/rtl): `Preprocessing/rtl`
- [Waveform data](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/io.py): `IR_backtracking/rca_core/io.py`

### RTL and protocol analysis

- [RTL intermediate records](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/ir_builder.py): `IR_backtracking/ir_builder.py`
- [Signal aliases](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/alias_engine.py): `IR_backtracking/alias_engine.py`
- [AXI-Lite rules](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/protocols/axi_lite/adapter.py): `IR_backtracking/protocols/axi_lite/adapter.py`
- [Signal grouping](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/protocols/axi_lite/signal_map.py): `IR_backtracking/protocols/axi_lite/signal_map.py`
- [Datapath semantics](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/semantic_datapath_analysis.py): `IR_backtracking/rca_core/semantic_datapath_analysis.py`
- [Memory write checks](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/semantic_checks/memory_write_analysis.py): `IR_backtracking/semantic_checks/memory_write_analysis.py`
- [FSM and temporal checks](https://github.com/meenalgada142/waveeye/tree/main/IR_backtracking): `IR_backtracking`

### Root cause analysis

- [Causal obligations](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/contracts.py): `IR_backtracking/rca_core/contracts.py`
- [RCA core engine](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/engine.py): `IR_backtracking/rca_core/engine.py`
- [Predicate backtracking](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/predicate_backtrack.py): `IR_backtracking/rca_core/predicate_backtrack.py`
- [Causal graph](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_core/causal_graph.py): `IR_backtracking/rca_core/causal_graph.py`
- [Root cause resolution](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/rca_resolver.py): `IR_backtracking/rca_resolver.py`

### Verdicts and reports

- [Diagnosis report](https://github.com/meenalgada142/waveeye/blob/main/IR_backtracking/reports/console_diagnosis.py): `IR_backtracking/reports/console_diagnosis.py`
- [Proof and analysis reports](https://github.com/meenalgada142/waveeye/tree/main/IR_backtracking/reports): `IR_backtracking/reports`
- **Analysis output files**

### Other components

- **Engineer**

## Connections

- Engineer → Interactive entry: provides inputs
- Interactive entry → VCD preprocessing: starts analysis
- VCD preprocessing → Waveform data: converts VCD (evidence: `Preprocessing/vcd/upload_run_convert_rtl_tb.py`)
- RTL preprocessing → RTL intermediate records: parses RTL
- RTL intermediate records → Signal aliases: resolves aliases
- RTL intermediate records → AXI-Lite rules: checks handshakes
- AXI-Lite rules → Signal grouping: groups signals (evidence: `IR_backtracking/protocols/axi_lite/adapter.py`)
- RTL intermediate records → Datapath semantics: checks mappings
- RTL intermediate records → Memory write checks: checks writes
- Waveform data → AXI-Lite rules: supplies cycles (evidence: `IR_backtracking/protocols/axi_lite/adapter.py`)
- Waveform data → FSM and temporal checks: supplies traces (evidence: `IR_backtracking/rca_core/io.py`)
- AXI-Lite rules → Causal obligations: defines obligations (evidence: `IR_backtracking/protocols/axi_lite/adapter.py`)
- Causal obligations → RCA core engine: evaluates (evidence: `IR_backtracking/rca_core/engine.py`)
- RCA core engine → Predicate backtracking: backtracks predicates (evidence: `IR_backtracking/rca_core/engine.py`)
- RCA core engine → Causal graph: builds dependencies (evidence: `IR_backtracking/rca_core/engine.py`)
- Datapath semantics → Root cause resolution: informs verdict
- Predicate backtracking → Root cause resolution: supports cause
- Causal graph → Root cause resolution: supports cause (evidence: `IR_backtracking/rca_resolver.py`)
- Root cause resolution → Diagnosis report: renders verdict
- Diagnosis report → Proof and analysis reports: details evidence
- Proof and analysis reports → Analysis output files: writes reports
- Analysis output files → Engineer: returns findings
