# orurh/causal_slam architecture

> Architecture diagram of the GitHub repository orurh/causal_slam, 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/orurh/causal_slam
- Repository: https://github.com/orurh/causal_slam

## Overview

Causal-SLAM is an experimental temporal-integrity and gating layer for LiDAR/IMU SLAM, not a mapping estimator. Its main live workflow adapts ROS sensor/TF input, analyzes timing and coverage, builds diagnostics and a map-update decision, then publishes health and checked LiDAR for a downstream estimator. A separate rosbag2 workflow analyzes recorded data and produces reports; session tooling supports bag discovery and repeatable analysis setup. The README documents these capabilities, while several application and rendering implementations were not excerpted, so those links are documented rather than inferred from unsampled code.

Main entry points: [`src/application/temporal_monitor/temporal_monitor_pipeline.cc`](https://github.com/orurh/causal_slam/blob/main/src/application/temporal_monitor/temporal_monitor_pipeline.cc) (Monitor Pipeline), [`src/apps/ros2/temporal_monitor_node.cc`](https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/temporal_monitor_node.cc) (Live Monitor), [`src/presentation/report/temporal_report_builder.cc`](https://github.com/orurh/causal_slam/blob/main/src/presentation/report/temporal_report_builder.cc) (Report Builder), [`src/apps/ros2/analyze_bag_app.cc`](https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/analyze_bag_app.cc) (Bag Analyzer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ros["ROS Interfaces"]
  node_monitor["Live Monitor"]
  node_checked["Checked LiDAR"]
  node_session["Session Tools<br/>[session_app.cc]"]
end

subgraph group_analysis["Temporal Analysis"]
  node_pipeline["Monitor Pipeline"]
  node_timing["Stream Timing"]
  node_scan["Scan Window"]
  node_pointtime["Point Time"]
  node_coverage["IMU Coverage"]
  node_tf["Transform Age"]
  node_offline["Offline Analysis"]
end

subgraph group_offline["Offline Evidence"]
  node_analyze["Bag Analyzer<br/>[analyze_bag_app.cc]"]
  node_report["Report Builder"]
  node_json["JSON Report"]
  node_html["HTML Report"]
end

subgraph group_output["Decisions and Reports"]
  node_diagnostics["Temporal Diagnostics"]
  node_decision["Map Update Policy"]
end

node_sensors(("LiDAR / IMU / TF"))
node_estimator["SLAM / LIO"]
node_bag[("Rosbag2 Input")]

node_sensors -->|"feeds"| node_monitor
node_monitor -->|"observes data"| node_pipeline
node_pipeline -->|"tracks timing"| node_timing
node_pipeline -->|"estimates window"| node_scan
node_pipeline -->|"extracts point time"| node_pointtime
node_pipeline -->|"checks coverage"| node_coverage
node_pipeline -->|"analyzes transforms"| node_tf
node_pipeline -->|"builds snapshot"| node_diagnostics
node_pipeline -->|"builds decision"| node_decision
node_monitor -->|"forwards checked data"| node_checked
node_checked -->|"feeds estimator"| node_estimator
node_monitor -->|"publishes health"| node_diagnostics
node_monitor -->|"publishes decision"| node_decision
node_bag -->|"provides recording"| node_analyze
node_analyze -->|"runs analysis"| node_offline
node_offline -->|"supplies evidence"| node_report
node_analyze -->|"builds report"| node_report
node_report -->|"renders JSON"| node_json
node_report -.->|"optionally renders HTML"| node_html
node_session -->|"discovers and plays"| node_bag

click node_monitor "https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/temporal_monitor_node.cc"
click node_pipeline "https://github.com/orurh/causal_slam/blob/main/src/application/temporal_monitor/temporal_monitor_pipeline.cc"
click node_timing "https://github.com/orurh/causal_slam/blob/main/src/domain/telemetry/stream_timing_tracker.cc"
click node_scan "https://github.com/orurh/causal_slam/blob/main/src/domain/sensors/lidar/lidar_scan_window_estimator.cc"
click node_pointtime "https://github.com/orurh/causal_slam/blob/main/src/domain/sensors/pointcloud/point_cloud2_time_field_extractor.cc"
click node_coverage "https://github.com/orurh/causal_slam/blob/main/src/domain/sensors/imu/imu_coverage_analyzer.cc"
click node_tf "https://github.com/orurh/causal_slam/blob/main/src/domain/sensors/transform/transform_age_analyzer.cc"
click node_diagnostics "https://github.com/orurh/causal_slam/blob/main/src/domain/diagnostics/temporal_diagnostics.cc"
click node_decision "https://github.com/orurh/causal_slam/blob/main/src/domain/policy/map_update_decision.h"
click node_checked "https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/temporal_monitor_node.cc"
click node_analyze "https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/analyze_bag_app.cc"
click node_offline "https://github.com/orurh/causal_slam/blob/main/src/application/offline_analysis/offline_stream_timing_fault_analyzer.cc"
click node_report "https://github.com/orurh/causal_slam/blob/main/src/presentation/report/temporal_report_builder.cc"
click node_json "https://github.com/orurh/causal_slam/blob/main/src/presentation/render/offline_temporal_report_json_renderer.cc"
click node_html "https://github.com/orurh/causal_slam/blob/main/src/presentation/render/offline_temporal_report_html_renderer.cc"
click node_session "https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/session_app.cc"

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_monitor,node_checked,node_session toneBlue
class node_pipeline,node_timing,node_scan,node_pointtime,node_coverage,node_tf,node_offline,node_bag toneAmber
class node_analyze,node_report,node_json,node_html toneMint
class node_diagnostics,node_decision toneRose
class node_sensors,node_estimator toneIndigo
```

## Components

### ROS Interfaces

- [Live Monitor](https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/temporal_monitor_node.cc): `src/apps/ros2/temporal_monitor_node.cc`
- [Checked LiDAR](https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/temporal_monitor_node.cc): `src/apps/ros2/temporal_monitor_node.cc`
- [Session Tools](https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/session_app.cc): `src/apps/ros2/session_app.cc`

### Temporal Analysis

- [Monitor Pipeline](https://github.com/orurh/causal_slam/blob/main/src/application/temporal_monitor/temporal_monitor_pipeline.cc): `src/application/temporal_monitor/temporal_monitor_pipeline.cc`
- [Stream Timing](https://github.com/orurh/causal_slam/blob/main/src/domain/telemetry/stream_timing_tracker.cc): `src/domain/telemetry/stream_timing_tracker.cc`
- [Scan Window](https://github.com/orurh/causal_slam/blob/main/src/domain/sensors/lidar/lidar_scan_window_estimator.cc): `src/domain/sensors/lidar/lidar_scan_window_estimator.cc`
- [Point Time](https://github.com/orurh/causal_slam/blob/main/src/domain/sensors/pointcloud/point_cloud2_time_field_extractor.cc): `src/domain/sensors/pointcloud/point_cloud2_time_field_extractor.cc`
- [IMU Coverage](https://github.com/orurh/causal_slam/blob/main/src/domain/sensors/imu/imu_coverage_analyzer.cc): `src/domain/sensors/imu/imu_coverage_analyzer.cc`
- [Transform Age](https://github.com/orurh/causal_slam/blob/main/src/domain/sensors/transform/transform_age_analyzer.cc): `src/domain/sensors/transform/transform_age_analyzer.cc`
- [Offline Analysis](https://github.com/orurh/causal_slam/blob/main/src/application/offline_analysis/offline_stream_timing_fault_analyzer.cc): `src/application/offline_analysis/offline_stream_timing_fault_analyzer.cc`

### Offline Evidence

- [Bag Analyzer](https://github.com/orurh/causal_slam/blob/main/src/apps/ros2/analyze_bag_app.cc): `src/apps/ros2/analyze_bag_app.cc`
- [Report Builder](https://github.com/orurh/causal_slam/blob/main/src/presentation/report/temporal_report_builder.cc): `src/presentation/report/temporal_report_builder.cc`
- [JSON Report](https://github.com/orurh/causal_slam/blob/main/src/presentation/render/offline_temporal_report_json_renderer.cc): `src/presentation/render/offline_temporal_report_json_renderer.cc`
- [HTML Report](https://github.com/orurh/causal_slam/blob/main/src/presentation/render/offline_temporal_report_html_renderer.cc): `src/presentation/render/offline_temporal_report_html_renderer.cc`

### Decisions and Reports

- [Temporal Diagnostics](https://github.com/orurh/causal_slam/blob/main/src/domain/diagnostics/temporal_diagnostics.cc): `src/domain/diagnostics/temporal_diagnostics.cc`
- [Map Update Policy](https://github.com/orurh/causal_slam/blob/main/src/domain/policy/map_update_decision.h): `src/domain/policy/map_update_decision.h`

### Other components

- **LiDAR / IMU / TF**
- **SLAM / LIO**
- **Rosbag2 Input**

## Connections

- LiDAR / IMU / TF → Live Monitor: feeds (evidence: `README.md`)
- Live Monitor → Monitor Pipeline: observes data
- Monitor Pipeline → Stream Timing: tracks timing
- Monitor Pipeline → Scan Window: estimates window
- Monitor Pipeline → Point Time: extracts point time
- Monitor Pipeline → IMU Coverage: checks coverage (evidence: `src/application/temporal_monitor/temporal_monitor_pipeline.cc`)
- Monitor Pipeline → Transform Age: analyzes transforms
- Monitor Pipeline → Temporal Diagnostics: builds snapshot (evidence: `src/application/temporal_monitor/temporal_monitor_pipeline.cc`)
- Monitor Pipeline → Map Update Policy: builds decision
- Live Monitor → Checked LiDAR: forwards checked data (evidence: `README.md`)
- Checked LiDAR → SLAM / LIO: feeds estimator (evidence: `README.md`)
- Live Monitor → Temporal Diagnostics: publishes health (evidence: `README.md`)
- Live Monitor → Map Update Policy: publishes decision (evidence: `README.md`)
- Rosbag2 Input → Bag Analyzer: provides recording (evidence: `README.md`)
- Bag Analyzer → Offline Analysis: runs analysis (evidence: `README.md`)
- Offline Analysis → Report Builder: supplies evidence (evidence: `README.md`)
- Bag Analyzer → Report Builder: builds report (evidence: `README.md`)
- Report Builder → JSON Report: renders JSON (evidence: `README.md`)
- Report Builder → HTML Report: optionally renders HTML (evidence: `README.md`)
- Session Tools → Rosbag2 Input: discovers and plays (evidence: `src/apps/ros2/session_app.cc`)
