# udit-agarwal20/avr-map architecture

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

- Interactive diagram: https://gitdiagram.com/udit-agarwal20/avr-map
- Repository: https://github.com/udit-agarwal20/avr-map

## Overview

AVR-Map combines a portable C++ adaptive LiDAR-mapping core with the AVR Console, a frozen operator-inspection demo, and offline recorded-sequence benchmarking. The mapping workflow accepts a frame, builds evidence, chooses resolution with policy and temporal hysteresis, updates a persistent hierarchy using cached observations for replay/refinement, and can expose dynamic and semantic cues. The Console selects demo scenarios and visualizes perception, resolution and dynamics alongside comparison, diagnostics, configuration and benchmark views. ROS 2 adapters and production inference are planned, not present. Some frontend and benchmark wiring is inferred only from names and documented scope; unsampled internals are not asserted.

Main entry points: [`backend/cpp/avr_mapping_core/src/persistent_adaptive_frame_pipeline.cpp`](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/persistent_adaptive_frame_pipeline.cpp) (Frame Pipeline), [`frontend/src/pages`](https://github.com/udit-agarwal20/avr-map/tree/main/frontend/src/pages) (Operator Views), [`backend/cpp/avr_benchmark/src/main.cpp`](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_benchmark/src/main.cpp) (Benchmark Runner), [`frontend/src/visualization/PerceptionViewport.tsx`](https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/visualization/PerceptionViewport.tsx) (Perception Viewport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mapping["Mapping Core"]
  node_frame_pipeline["Frame Pipeline"]
  node_frame_evidence["Frame Evidence<br/>[frame_evidence.cpp]"]
  node_resolution["Resolution Policy"]
  node_hysteresis["Resolution Hysteresis"]
  node_semantic["Semantic Provider"]
  node_dynamic["Dynamic Clustering"]
  node_persistent_map[("Adaptive Map")]
  node_replay_cache[("Observation Cache")]
  node_spatial["Spatial Primitives"]
end

subgraph group_offline["Offline Evaluation"]
  node_sequence["Sequence Loader<br/>[sequence.cpp]"]
  node_benchmark["Benchmark Runner<br/>[main.cpp]"]
  node_artifacts["Benchmark Artifacts<br/>[artifacts.cpp]"]
  node_tools["Recorded-Input Tools"]
end

subgraph group_console["AVR Console"]
  node_app["Console Routes<br/>[App.tsx]"]
  node_pages["Operator Views"]
  node_store["Console State<br/>[useConsoleStore.ts]"]
  node_runtime["Frame Runtime"]
  node_fixtures["Demo Scenarios<br/>[scenarios.ts]"]
end

subgraph group_visualization["Scene Inspection"]
  node_viewport["Perception Viewport"]
  node_scene["Perception Scene<br/>[PerceptionScene.ts]"]
  node_camera["Camera Controls"]
  node_comparison["Comparison Canvas"]
end

node_lidar(("LiDAR Frames"))
node_recorded(("Recorded Sequence"))

node_lidar -->|"submits frames"| node_frame_pipeline
node_frame_pipeline -->|"builds evidence"| node_frame_evidence
node_frame_pipeline -.->|"requests inference"| node_semantic
node_frame_pipeline -->|"decides resolution"| node_resolution
node_frame_pipeline -->|"previews policy"| node_hysteresis
node_frame_pipeline -->|"fuses and refines"| node_persistent_map
node_frame_pipeline -->|"stages observations"| node_replay_cache
node_frame_pipeline -->|"extracts dynamics"| node_dynamic
node_frame_pipeline -->|"uses grid operations"| node_spatial
node_recorded -->|"provides input"| node_tools
node_tools -->|"adapts sequence"| node_sequence
node_benchmark -->|"loads sequence"| node_sequence
node_benchmark -->|"writes results"| node_artifacts
node_benchmark -->|"benchmarks mapping"| node_frame_pipeline
node_app -->|"routes views"| node_pages
node_pages -->|"reads and updates"| node_store
node_store -->|"selects scenario"| node_runtime
node_runtime -->|"uses demo data"| node_fixtures
node_pages -->|"presents perception"| node_viewport
node_viewport -->|"renders scene"| node_scene
node_viewport -->|"controls camera"| node_camera
node_pages -->|"compares views"| node_comparison

click node_frame_pipeline "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/persistent_adaptive_frame_pipeline.cpp"
click node_frame_evidence "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/frame_evidence.cpp"
click node_resolution "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/resolution_controller.cpp"
click node_hysteresis "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/resolution_hysteresis.cpp"
click node_semantic "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/include/avr_mapping/semantic_provider.hpp"
click node_dynamic "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/dynamic_clusterer.cpp"
click node_persistent_map "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/persistent_adaptive_map.cpp"
click node_replay_cache "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/recent_observation_cache.cpp"
click node_spatial "https://github.com/udit-agarwal20/avr-map/tree/main/backend/cpp/avr_spatial"
click node_sequence "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_benchmark/src/sequence.cpp"
click node_benchmark "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_benchmark/src/main.cpp"
click node_artifacts "https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_benchmark/src/artifacts.cpp"
click node_tools "https://github.com/udit-agarwal20/avr-map/blob/main/tools/recorded_sequence_adapter.py"
click node_app "https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/App.tsx"
click node_pages "https://github.com/udit-agarwal20/avr-map/tree/main/frontend/src/pages"
click node_store "https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/stores/useConsoleStore.ts"
click node_runtime "https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/runtime/PerceptionFrameRuntime.ts"
click node_fixtures "https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/demo/scenarios.ts"
click node_viewport "https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/visualization/PerceptionViewport.tsx"
click node_scene "https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/visualization/PerceptionScene.ts"
click node_camera "https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/visualization/camera/CameraController.ts"
click node_comparison "https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/visualization/ComparisonCanvas.ts"

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_frame_pipeline,node_frame_evidence,node_resolution,node_hysteresis,node_semantic,node_dynamic,node_persistent_map,node_replay_cache,node_spatial toneBlue
class node_sequence,node_benchmark,node_artifacts,node_tools toneAmber
class node_app,node_pages,node_store,node_runtime,node_fixtures toneMint
class node_viewport,node_scene,node_camera,node_comparison toneRose
class node_lidar,node_recorded toneIndigo
```

## Components

### Mapping Core

- [Frame Pipeline](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/persistent_adaptive_frame_pipeline.cpp): `backend/cpp/avr_mapping_core/src/persistent_adaptive_frame_pipeline.cpp`
- [Frame Evidence](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/frame_evidence.cpp): `backend/cpp/avr_mapping_core/src/frame_evidence.cpp`
- [Resolution Policy](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/resolution_controller.cpp): `backend/cpp/avr_mapping_core/src/resolution_controller.cpp`
- [Resolution Hysteresis](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/resolution_hysteresis.cpp): `backend/cpp/avr_mapping_core/src/resolution_hysteresis.cpp`
- [Semantic Provider](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/include/avr_mapping/semantic_provider.hpp): `backend/cpp/avr_mapping_core/include/avr_mapping/semantic_provider.hpp`
- [Dynamic Clustering](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/dynamic_clusterer.cpp): `backend/cpp/avr_mapping_core/src/dynamic_clusterer.cpp`
- [Adaptive Map](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/persistent_adaptive_map.cpp): `backend/cpp/avr_mapping_core/src/persistent_adaptive_map.cpp`
- [Observation Cache](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_mapping_core/src/recent_observation_cache.cpp): `backend/cpp/avr_mapping_core/src/recent_observation_cache.cpp`
- [Spatial Primitives](https://github.com/udit-agarwal20/avr-map/tree/main/backend/cpp/avr_spatial): `backend/cpp/avr_spatial`

### Offline Evaluation

- [Sequence Loader](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_benchmark/src/sequence.cpp): `backend/cpp/avr_benchmark/src/sequence.cpp`
- [Benchmark Runner](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_benchmark/src/main.cpp): `backend/cpp/avr_benchmark/src/main.cpp`
- [Benchmark Artifacts](https://github.com/udit-agarwal20/avr-map/blob/main/backend/cpp/avr_benchmark/src/artifacts.cpp): `backend/cpp/avr_benchmark/src/artifacts.cpp`
- [Recorded-Input Tools](https://github.com/udit-agarwal20/avr-map/blob/main/tools/recorded_sequence_adapter.py): `tools/recorded_sequence_adapter.py`

### AVR Console

- [Console Routes](https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Operator Views](https://github.com/udit-agarwal20/avr-map/tree/main/frontend/src/pages): `frontend/src/pages`
- [Console State](https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/stores/useConsoleStore.ts): `frontend/src/stores/useConsoleStore.ts`
- [Frame Runtime](https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/runtime/PerceptionFrameRuntime.ts): `frontend/src/runtime/PerceptionFrameRuntime.ts`
- [Demo Scenarios](https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/demo/scenarios.ts): `frontend/src/demo/scenarios.ts`

### Scene Inspection

- [Perception Viewport](https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/visualization/PerceptionViewport.tsx): `frontend/src/visualization/PerceptionViewport.tsx`
- [Perception Scene](https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/visualization/PerceptionScene.ts): `frontend/src/visualization/PerceptionScene.ts`
- [Camera Controls](https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/visualization/camera/CameraController.ts): `frontend/src/visualization/camera/CameraController.ts`
- [Comparison Canvas](https://github.com/udit-agarwal20/avr-map/blob/main/frontend/src/visualization/ComparisonCanvas.ts): `frontend/src/visualization/ComparisonCanvas.ts`

### Other components

- **LiDAR Frames**
- **Recorded Sequence**

## Connections

- LiDAR Frames → Frame Pipeline: submits frames
- Frame Pipeline → Frame Evidence: builds evidence
- Frame Pipeline → Semantic Provider: requests inference
- Frame Pipeline → Resolution Policy: decides resolution
- Frame Pipeline → Resolution Hysteresis: previews policy
- Frame Pipeline → Adaptive Map: fuses and refines
- Frame Pipeline → Observation Cache: stages observations
- Frame Pipeline → Dynamic Clustering: extracts dynamics
- Frame Pipeline → Spatial Primitives: uses grid operations
- Recorded Sequence → Recorded-Input Tools: provides input
- Recorded-Input Tools → Sequence Loader: adapts sequence
- Benchmark Runner → Sequence Loader: loads sequence
- Benchmark Runner → Benchmark Artifacts: writes results
- Benchmark Runner → Frame Pipeline: benchmarks mapping
- Console Routes → Operator Views: routes views
- Operator Views → Console State: reads and updates
- Console State → Frame Runtime: selects scenario
- Frame Runtime → Demo Scenarios: uses demo data
- Operator Views → Perception Viewport: presents perception
- Perception Viewport → Perception Scene: renders scene
- Perception Viewport → Camera Controls: controls camera
- Operator Views → Comparison Canvas: compares views