# reagon0/kairosloop architecture

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

- Interactive diagram: https://gitdiagram.com/reagon0/kairosloop
- Repository: https://github.com/reagon0/kairosloop

## Overview

KairosLoop is a closed-loop CNC tool-wear compensation system. Its principal workflow acquires gauge readings, computes feature values and deviations, records measurements, evaluates compensation rules, and routes safe offset requests to a controller; operators monitor activity through the dashboard. Configuration, tool lifecycle tracking, and hardware simulation are additional product branches. The README documents several workflow links; sampled source confirms selected service, gateway, and WebSocket interactions, but many runtime details were not inspected.

Main entry points: [`measurement/services.py`](https://github.com/reagon0/kairosloop/blob/main/measurement/services.py) (Gauge Acquisition), [`compensation/engine.py`](https://github.com/reagon0/kairosloop/blob/main/compensation/engine.py) (Compensation Engine), [`dashboard/views.py`](https://github.com/reagon0/kairosloop/blob/main/dashboard/views.py) (Setup and Configuration), [`controller/gateway.py`](https://github.com/reagon0/kairosloop/blob/main/controller/gateway.py) (Offset Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_measure["Measurement"]
  node_acquisition["Gauge Acquisition<br/>[services.py]"]
  node_n1700["N1700 Driver<br/>[n1700.py]"]
  node_capture["Measurement Capture<br/>[capture.py]"]
  node_feature["Feature Calculation<br/>[models.py]"]
  node_measurement[("Measurement Records<br/>[models.py]")]
end

subgraph group_compensate["Compensation"]
  node_compensation_rules[("Compensation Rules<br/>[models.py]")]
  node_engine["Compensation Engine<br/>[engine.py]"]
  node_events[("Compensation Events<br/>[models.py]")]
end

subgraph group_machine["Machine and Tools"]
  node_machine_config[("Machine Configuration<br/>[models.py]")]
  node_gateway["Offset Gateway<br/>[gateway.py]"]
  node_drivers["Controller Drivers<br/>[drivers.py]"]
  node_tooling[("Tool Lifecycle<br/>[models.py]")]
end

subgraph group_operator["Operator Interface"]
  node_dashboard["Live Dashboard<br/>[consumers.py]"]
  node_setup["Setup and Configuration<br/>[views.py]"]
end

subgraph group_simulation["Simulation"]
  node_sim_gauge["Gauge Simulator<br/>[gauge.py]"]
  node_sim_plc["Test PLC<br/>[plc.py]"]
  node_sim_seed["Demo Data Setup<br/>[seed.py]"]
  node_wear_sim["Tool Wear Simulation<br/>[tool_wear.py]"]
end

node_gauge(("N1700 Gauge"))
node_controller{{"CNC Controller"}}
node_operator_actor(("Operator"))

node_gauge -.->|"supplies readings"| node_acquisition
node_acquisition -->|"initializes and reads"| node_n1700
node_acquisition -.->|"records readings"| node_measurement
node_capture -.->|"calculates features"| node_feature
node_feature -.->|"produces values"| node_measurement
node_measurement -.->|"triggers processing"| node_engine
node_engine -->|"evaluates rules"| node_compensation_rules
node_engine -->|"submits offsets"| node_gateway
node_gateway -->|"checks assignment limits"| node_tooling
node_gateway -.->|"executes approved writes"| node_drivers
node_drivers -.->|"writes offsets"| node_controller
node_engine -.->|"logs decisions"| node_events
node_operator_actor -.->|"monitors live data"| node_dashboard
node_dashboard -->|"issues gauge commands"| node_acquisition
node_dashboard -->|"controls simulation"| node_sim_plc
node_operator_actor -.->|"configures system"| node_setup
node_setup -.->|"edits settings"| node_machine_config
node_setup -.->|"edits rules"| node_compensation_rules
node_setup -.->|"manages tools"| node_tooling
node_sim_gauge -.->|"simulates readings"| node_acquisition
node_sim_plc -->|"implements test controller"| node_drivers
node_sim_plc -.->|"tracks simulated wear"| node_wear_sim
node_sim_seed -.->|"creates demo configuration"| node_machine_config
node_sim_seed -.->|"creates demo rules"| node_compensation_rules

click node_acquisition "https://github.com/reagon0/kairosloop/blob/main/measurement/services.py"
click node_n1700 "https://github.com/reagon0/kairosloop/blob/main/measurement/n1700.py"
click node_capture "https://github.com/reagon0/kairosloop/blob/main/measurement/capture.py"
click node_feature "https://github.com/reagon0/kairosloop/blob/main/measurement/models.py"
click node_measurement "https://github.com/reagon0/kairosloop/blob/main/measurement/models.py"
click node_compensation_rules "https://github.com/reagon0/kairosloop/blob/main/compensation/models.py"
click node_engine "https://github.com/reagon0/kairosloop/blob/main/compensation/engine.py"
click node_events "https://github.com/reagon0/kairosloop/blob/main/compensation/models.py"
click node_machine_config "https://github.com/reagon0/kairosloop/blob/main/controller/models.py"
click node_gateway "https://github.com/reagon0/kairosloop/blob/main/controller/gateway.py"
click node_drivers "https://github.com/reagon0/kairosloop/blob/main/controller/drivers.py"
click node_tooling "https://github.com/reagon0/kairosloop/blob/main/tooling/models.py"
click node_dashboard "https://github.com/reagon0/kairosloop/blob/main/dashboard/consumers.py"
click node_setup "https://github.com/reagon0/kairosloop/blob/main/dashboard/views.py"
click node_sim_gauge "https://github.com/reagon0/kairosloop/blob/main/simulator/gauge.py"
click node_sim_plc "https://github.com/reagon0/kairosloop/blob/main/simulator/plc.py"
click node_sim_seed "https://github.com/reagon0/kairosloop/blob/main/simulator/seed.py"
click node_wear_sim "https://github.com/reagon0/kairosloop/blob/main/simulator/tool_wear.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_acquisition,node_n1700,node_capture,node_feature,node_measurement toneBlue
class node_compensation_rules,node_engine,node_events toneAmber
class node_machine_config,node_gateway,node_drivers,node_tooling toneMint
class node_dashboard,node_setup toneRose
class node_sim_gauge,node_sim_plc,node_sim_seed,node_wear_sim,node_gauge,node_controller,node_operator_actor toneIndigo
```

## Components

### Measurement

- [Gauge Acquisition](https://github.com/reagon0/kairosloop/blob/main/measurement/services.py): `measurement/services.py`
- [N1700 Driver](https://github.com/reagon0/kairosloop/blob/main/measurement/n1700.py): `measurement/n1700.py`
- [Measurement Capture](https://github.com/reagon0/kairosloop/blob/main/measurement/capture.py): `measurement/capture.py`
- [Feature Calculation](https://github.com/reagon0/kairosloop/blob/main/measurement/models.py): `measurement/models.py`
- [Measurement Records](https://github.com/reagon0/kairosloop/blob/main/measurement/models.py): `measurement/models.py`

### Compensation

- [Compensation Rules](https://github.com/reagon0/kairosloop/blob/main/compensation/models.py): `compensation/models.py`
- [Compensation Engine](https://github.com/reagon0/kairosloop/blob/main/compensation/engine.py): `compensation/engine.py`
- [Compensation Events](https://github.com/reagon0/kairosloop/blob/main/compensation/models.py): `compensation/models.py`

### Machine and Tools

- [Machine Configuration](https://github.com/reagon0/kairosloop/blob/main/controller/models.py): `controller/models.py`
- [Offset Gateway](https://github.com/reagon0/kairosloop/blob/main/controller/gateway.py): `controller/gateway.py`
- [Controller Drivers](https://github.com/reagon0/kairosloop/blob/main/controller/drivers.py): `controller/drivers.py`
- [Tool Lifecycle](https://github.com/reagon0/kairosloop/blob/main/tooling/models.py): `tooling/models.py`

### Operator Interface

- [Live Dashboard](https://github.com/reagon0/kairosloop/blob/main/dashboard/consumers.py): `dashboard/consumers.py`
- [Setup and Configuration](https://github.com/reagon0/kairosloop/blob/main/dashboard/views.py): `dashboard/views.py`

### Simulation

- [Gauge Simulator](https://github.com/reagon0/kairosloop/blob/main/simulator/gauge.py): `simulator/gauge.py`
- [Test PLC](https://github.com/reagon0/kairosloop/blob/main/simulator/plc.py): `simulator/plc.py`
- [Demo Data Setup](https://github.com/reagon0/kairosloop/blob/main/simulator/seed.py): `simulator/seed.py`
- [Tool Wear Simulation](https://github.com/reagon0/kairosloop/blob/main/simulator/tool_wear.py): `simulator/tool_wear.py`

### Other components

- **N1700 Gauge**
- **CNC Controller**
- **Operator**

## Connections

- N1700 Gauge → Gauge Acquisition: supplies readings
- Gauge Acquisition → N1700 Driver: initializes and reads (evidence: `measurement/services.py`)
- Gauge Acquisition → Measurement Records: records readings (evidence: `measurement/services.py`)
- Measurement Capture → Feature Calculation: calculates features (evidence: `measurement/capture.py`)
- Feature Calculation → Measurement Records: produces values (evidence: `measurement/models.py`)
- Measurement Records → Compensation Engine: triggers processing
- Compensation Engine → Compensation Rules: evaluates rules (evidence: `compensation/engine.py`)
- Compensation Engine → Offset Gateway: submits offsets (evidence: `compensation/engine.py`)
- Offset Gateway → Tool Lifecycle: checks assignment limits (evidence: `controller/gateway.py`)
- Offset Gateway → Controller Drivers: executes approved writes (evidence: `controller/gateway.py`)
- Controller Drivers → CNC Controller: writes offsets
- Compensation Engine → Compensation Events: logs decisions (evidence: `compensation/engine.py`)
- Operator → Live Dashboard: monitors live data
- Live Dashboard → Gauge Acquisition: issues gauge commands (evidence: `dashboard/consumers.py`)
- Live Dashboard → Test PLC: controls simulation (evidence: `dashboard/consumers.py`)
- Operator → Setup and Configuration: configures system
- Setup and Configuration → Machine Configuration: edits settings
- Setup and Configuration → Compensation Rules: edits rules
- Setup and Configuration → Tool Lifecycle: manages tools
- Gauge Simulator → Gauge Acquisition: simulates readings
- Test PLC → Controller Drivers: implements test controller (evidence: `controller/drivers.py`)
- Test PLC → Tool Wear Simulation: tracks simulated wear (evidence: `simulator/plc.py`)
- Demo Data Setup → Machine Configuration: creates demo configuration (evidence: `simulator/seed.py`)
- Demo Data Setup → Compensation Rules: creates demo rules (evidence: `simulator/seed.py`)