# anoor3/argus architecture

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

- Interactive diagram: https://gitdiagram.com/anoor3/argus
- Repository: https://github.com/anoor3/argus
- Video tour (about a minute): https://gitdiagram.com/anoor3/argus/video

## Overview

ARGUS is an FPGA-based hardware validation instrument with host software for running repeatable test plans and reviewing captured results. The principal workflow is a user launching a plan, the host issuing register commands over a transport, and the instrument observing or stimulating the DUT while recording timestamped events. The tree shows distinct control, capture, stimulus, and safety subsystems. Host-side calls are supported by sampled source; RTL relationships are kept conservative because RTL implementation excerpts were not provided.

Main entry points: [`host/argus/cli.py`](https://github.com/anoor3/argus/blob/main/host/argus/cli.py) (Host CLI), [`host/argus/client.py`](https://github.com/anoor3/argus/blob/main/host/argus/client.py) (Register client), [`host/argus/plan.py`](https://github.com/anoor3/argus/blob/main/host/argus/plan.py) (Plan runner), [`host/argus/report.py`](https://github.com/anoor3/argus/blob/main/host/argus/report.py) (Plan reporting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host automation"]
  node_cli["Host CLI<br/>[cli.py]"]
  node_plan["Plan runner<br/>[plan.py]"]
  node_client["Register client<br/>[client.py]"]
  node_protocol["Frame protocol<br/>[protocol.py]"]
  node_transport["Serial transport"]
  node_mock["Mock instrument<br/>[mock.py]"]
  node_report["Plan reporting<br/>[report.py]"]
  node_trace["Trace decoder<br/>[trace.py]"]
  node_plot["Timeline plotting<br/>[plot.py]"]
end

subgraph group_control["Instrument control"]
  node_instrument["ARGUS FPGA<br/>[argus_core.sv]"]
  node_router["Command router<br/>[command_router.sv]"]
  node_csr["Register bank<br/>[csr_bank.sv]"]
  node_sequencer["Test sequencer<br/>[test_sequencer.sv]"]
  node_trigger["Trigger engine<br/>[trigger_engine.sv]"]
end

subgraph group_dut["DUT interaction"]
  node_monitors["DUT monitors<br/>[gpio_monitor.sv]"]
  node_stimulus["Serial stimulus<br/>[i2c_master.sv]"]
  node_spi["SPI stimulus<br/>[spi_master.sv]"]
  node_adc["ADC bridge<br/>[adc_bridge.sv]"]
end

subgraph group_capture["Event capture"]
  node_timebase["Timebase<br/>[timebase.sv]"]
  node_capture["Capture subsystem"]
  node_logger["Event logger<br/>[event_logger.sv]"]
  node_tracebuf[("Trace buffer<br/>[trace_buffer.sv]")]
end

subgraph group_safety["Safety"]
  node_fault["Fault controller"]
  node_interlock["Safety interlock"]
end

node_user(("Engineer"))
node_dutdevice["Device under test"]

node_user -->|"runs plan"| node_cli
node_cli -->|"runs steps"| node_plan
node_cli -->|"creates"| node_client
node_cli -->|"formats results"| node_report
node_cli -.->|"opens serial"| node_transport
node_cli -.->|"selects mock"| node_mock
node_plan -->|"issues register ops"| node_client
node_client -->|"encodes commands"| node_protocol
node_client -->|"reads and writes"| node_transport
node_client -->|"decodes records"| node_trace
node_report -.->|"exports timeline"| node_plot
node_transport -->|"sends frames"| node_router
node_router -->|"routes register access"| node_csr
node_dutdevice -->|"signals"| node_monitors
node_stimulus -->|"drives bus"| node_dutdevice
node_spi -->|"drives bus"| node_dutdevice
node_adc -->|"interfaces signals"| node_dutdevice
node_monitors -->|"provides events"| node_capture
node_trigger -->|"triggers capture"| node_capture
node_timebase -->|"timestamps events"| node_logger
node_logger -->|"records events"| node_tracebuf
node_fault -->|"signals faults"| node_interlock

click node_cli "https://github.com/anoor3/argus/blob/main/host/argus/cli.py"
click node_plan "https://github.com/anoor3/argus/blob/main/host/argus/plan.py"
click node_client "https://github.com/anoor3/argus/blob/main/host/argus/client.py"
click node_protocol "https://github.com/anoor3/argus/blob/main/host/argus/protocol.py"
click node_mock "https://github.com/anoor3/argus/blob/main/host/argus/mock.py"
click node_report "https://github.com/anoor3/argus/blob/main/host/argus/report.py"
click node_trace "https://github.com/anoor3/argus/blob/main/host/argus/trace.py"
click node_plot "https://github.com/anoor3/argus/blob/main/host/argus/plot.py"
click node_instrument "https://github.com/anoor3/argus/blob/main/rtl/argus_core.sv"
click node_router "https://github.com/anoor3/argus/blob/main/rtl/command_router.sv"
click node_csr "https://github.com/anoor3/argus/blob/main/rtl/csr_bank.sv"
click node_sequencer "https://github.com/anoor3/argus/blob/main/rtl/test_sequencer.sv"
click node_trigger "https://github.com/anoor3/argus/blob/main/rtl/trigger_engine.sv"
click node_timebase "https://github.com/anoor3/argus/blob/main/rtl/timebase.sv"
click node_capture "https://github.com/anoor3/argus/blob/main/rtl/capture_subsystem.sv"
click node_logger "https://github.com/anoor3/argus/blob/main/rtl/event_logger.sv"
click node_tracebuf "https://github.com/anoor3/argus/blob/main/rtl/trace_buffer.sv"
click node_monitors "https://github.com/anoor3/argus/blob/main/rtl/gpio_monitor.sv"
click node_stimulus "https://github.com/anoor3/argus/blob/main/rtl/i2c_master.sv"
click node_spi "https://github.com/anoor3/argus/blob/main/rtl/spi_master.sv"
click node_adc "https://github.com/anoor3/argus/blob/main/rtl/adc_bridge.sv"
click node_fault "https://github.com/anoor3/argus/blob/main/rtl/fault_controller.sv"
click node_interlock "https://github.com/anoor3/argus/blob/main/rtl/safety_interlock.sv"

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_plan,node_client,node_protocol,node_transport,node_mock,node_report,node_trace,node_plot toneBlue
class node_instrument,node_router,node_csr,node_sequencer,node_trigger toneAmber
class node_monitors,node_stimulus,node_spi,node_adc toneMint
class node_timebase,node_capture,node_logger,node_tracebuf toneRose
class node_fault,node_interlock,node_user,node_dutdevice toneIndigo
```

## Components

### Host automation

- [Host CLI](https://github.com/anoor3/argus/blob/main/host/argus/cli.py): `host/argus/cli.py`
- [Plan runner](https://github.com/anoor3/argus/blob/main/host/argus/plan.py): `host/argus/plan.py`
- [Register client](https://github.com/anoor3/argus/blob/main/host/argus/client.py): `host/argus/client.py`
- [Frame protocol](https://github.com/anoor3/argus/blob/main/host/argus/protocol.py): `host/argus/protocol.py`
- **Serial transport**
- [Mock instrument](https://github.com/anoor3/argus/blob/main/host/argus/mock.py): `host/argus/mock.py`
- [Plan reporting](https://github.com/anoor3/argus/blob/main/host/argus/report.py): `host/argus/report.py`
- [Trace decoder](https://github.com/anoor3/argus/blob/main/host/argus/trace.py): `host/argus/trace.py`
- [Timeline plotting](https://github.com/anoor3/argus/blob/main/host/argus/plot.py): `host/argus/plot.py`

### Instrument control

- [ARGUS FPGA](https://github.com/anoor3/argus/blob/main/rtl/argus_core.sv): `rtl/argus_core.sv`
- [Command router](https://github.com/anoor3/argus/blob/main/rtl/command_router.sv): `rtl/command_router.sv`
- [Register bank](https://github.com/anoor3/argus/blob/main/rtl/csr_bank.sv): `rtl/csr_bank.sv`
- [Test sequencer](https://github.com/anoor3/argus/blob/main/rtl/test_sequencer.sv): `rtl/test_sequencer.sv`
- [Trigger engine](https://github.com/anoor3/argus/blob/main/rtl/trigger_engine.sv): `rtl/trigger_engine.sv`

### DUT interaction

- [DUT monitors](https://github.com/anoor3/argus/blob/main/rtl/gpio_monitor.sv): `rtl/gpio_monitor.sv`
- [Serial stimulus](https://github.com/anoor3/argus/blob/main/rtl/i2c_master.sv): `rtl/i2c_master.sv`
- [SPI stimulus](https://github.com/anoor3/argus/blob/main/rtl/spi_master.sv): `rtl/spi_master.sv`
- [ADC bridge](https://github.com/anoor3/argus/blob/main/rtl/adc_bridge.sv): `rtl/adc_bridge.sv`

### Event capture

- [Timebase](https://github.com/anoor3/argus/blob/main/rtl/timebase.sv): `rtl/timebase.sv`
- [Capture subsystem](https://github.com/anoor3/argus/blob/main/rtl/capture_subsystem.sv): `rtl/capture_subsystem.sv`
- [Event logger](https://github.com/anoor3/argus/blob/main/rtl/event_logger.sv): `rtl/event_logger.sv`
- [Trace buffer](https://github.com/anoor3/argus/blob/main/rtl/trace_buffer.sv): `rtl/trace_buffer.sv`

### Safety

- [Fault controller](https://github.com/anoor3/argus/blob/main/rtl/fault_controller.sv): `rtl/fault_controller.sv`
- [Safety interlock](https://github.com/anoor3/argus/blob/main/rtl/safety_interlock.sv): `rtl/safety_interlock.sv`

### Other components

- **Engineer**
- **Device under test**

## Connections

- Engineer → Host CLI: runs plan
- Host CLI → Plan runner: runs steps
- Host CLI → Register client: creates
- Host CLI → Plan reporting: formats results
- Host CLI → Serial transport: opens serial
- Host CLI → Mock instrument: selects mock
- Plan runner → Register client: issues register ops
- Register client → Frame protocol: encodes commands
- Register client → Serial transport: reads and writes
- Register client → Trace decoder: decodes records
- Plan reporting → Timeline plotting: exports timeline
- Serial transport → Command router: sends frames
- Command router → Register bank: routes register access
- Device under test → DUT monitors: signals
- Serial stimulus → Device under test: drives bus
- SPI stimulus → Device under test: drives bus
- ADC bridge → Device under test: interfaces signals
- DUT monitors → Capture subsystem: provides events
- Trigger engine → Capture subsystem: triggers capture
- Timebase → Event logger: timestamps events
- Event logger → Trace buffer: records events
- Fault controller → Safety interlock: signals faults