# aarnavkannan/sunhacks architecture

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

- Interactive diagram: https://gitdiagram.com/aarnavkannan/sunhacks
- Repository: https://github.com/aarnavkannan/sunhacks

## Overview

Sunhacks is an incident-reconstruction and review product: footage is processed into a scene package, then explored in a desktop viewer with motion analysis and an assistant. The tree also contains a parallel BackEnd pipeline, shared scene types, voice support, and a download-focused landing site. The README gives no product workflow details, so pipeline relationships below rely on build.py’s indexed imports; several frontend and integration relationships remain unshown in the excerpts and are omitted.

Main entry points: [`pipeline/src/reconstruct/build.py`](https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/build.py) (Scene builder), [`BackEnd/pipeline/src/reconstruct/build.py`](https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/build.py) (Backend builder), [`FrontEnd/app/src/gemini/engine.ts`](https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/gemini/engine.ts) (Scene engine), [`packages/assistant/src/tools/registry.ts`](https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/tools/registry.ts) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reconstruction["Scene reconstruction"]
  node_pipeline_build["Scene builder<br/>[build.py]"]
  node_pipeline_ingest["Footage ingest<br/>[ingest.py]"]
  node_pipeline_geometry["Geometry model<br/>[geometry.py]"]
  node_pipeline_models["Scene models<br/>[models.py]"]
  node_pipeline_cache[("Step cache<br/>[cache.py]")]
  node_pipeline_kinematics["Track kinematics<br/>[kinematics.py]"]
  node_backend_build["Backend builder<br/>[build.py]"]
  node_backend_geometry["Backend geometry<br/>[geometry.py]"]
  node_backend_models["Backend models<br/>[models.py]"]
  node_backend_cache[("Backend cache<br/>[cache.py]")]
  node_backend_kinematics["Backend kinematics<br/>[kinematics.py]"]
end

subgraph group_desktop["Desktop review"]
  node_scene_viewer["Scene viewer<br/>[SceneViewer.tsx]"]
  node_scene_engine["Scene engine<br/>[engine.ts]"]
  node_motion_planner["Motion planner<br/>[motion.ts]"]
  node_incident_spec["Incident spec<br/>[spec.ts]"]
  node_kinematics["Kinematics analysis<br/>[derive.ts]"]
  node_ingest_ui["Video ingest<br/>[ingest.ts]"]
  node_video_export["Video export<br/>[exportVideo.ts]"]
end

subgraph group_assistant["Assistant and voice"]
  node_assistant_session["Assistant session<br/>[session.ts]"]
  node_assistant_tools["Tool registry<br/>[registry.ts]"]
  node_scene_controller["Scene controller<br/>[controller.ts]"]
  node_mcp_server["MCP server<br/>[server.ts]"]
  node_system_prompt["System prompt<br/>[system-prompt.ts]"]
  node_voice_controller["Voice controller<br/>[controller.ts]"]
end

subgraph group_web["Product site"]
  node_landing_site["Landing site<br/>[App.tsx]"]
end

node_user(("Reviewer"))

node_pipeline_build -->|"uses ingest"| node_pipeline_ingest
node_pipeline_build -->|"uses geometry"| node_pipeline_geometry
node_pipeline_build -->|"uses models"| node_pipeline_models
node_pipeline_build -->|"uses cache"| node_pipeline_cache
node_pipeline_build -->|"uses kinematics"| node_pipeline_kinematics
node_backend_build -->|"uses geometry"| node_backend_geometry
node_backend_build -->|"uses models"| node_backend_models
node_backend_build -->|"uses cache"| node_backend_cache
node_backend_build -->|"uses kinematics"| node_backend_kinematics
node_scene_engine -->|"resolves spec"| node_incident_spec
node_scene_engine -->|"plans motion"| node_motion_planner
node_scene_engine -->|"builds roads"| node_incident_spec
node_assistant_session -->|"starts server"| node_mcp_server
node_assistant_session -->|"calls tools"| node_assistant_tools
node_mcp_server -->|"dispatches tools"| node_assistant_tools
node_assistant_tools -->|"invokes methods"| node_scene_controller
node_user -.->|"visits"| node_landing_site

click node_pipeline_build "https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/build.py"
click node_pipeline_ingest "https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/steps/ingest.py"
click node_pipeline_geometry "https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/geometry.py"
click node_pipeline_models "https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/models.py"
click node_pipeline_cache "https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/steps/cache.py"
click node_pipeline_kinematics "https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/steps/kinematics.py"
click node_backend_build "https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/build.py"
click node_backend_geometry "https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/geometry.py"
click node_backend_models "https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/models.py"
click node_backend_cache "https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/steps/cache.py"
click node_backend_kinematics "https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/steps/kinematics.py"
click node_scene_viewer "https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/SceneViewer.tsx"
click node_scene_engine "https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/gemini/engine.ts"
click node_motion_planner "https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/gemini/motion.ts"
click node_incident_spec "https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/gemini/spec.ts"
click node_kinematics "https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/kinematics/derive.ts"
click node_ingest_ui "https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/lib/ingest.ts"
click node_video_export "https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/lib/exportVideo.ts"
click node_assistant_session "https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/session.ts"
click node_assistant_tools "https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/tools/registry.ts"
click node_scene_controller "https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/controller.ts"
click node_mcp_server "https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/mcp/server.ts"
click node_system_prompt "https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/prompt/system-prompt.ts"
click node_voice_controller "https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/voice/controller.ts"
click node_landing_site "https://github.com/aarnavkannan/sunhacks/blob/main/landing/src/App.tsx"

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_pipeline_build,node_pipeline_ingest,node_pipeline_geometry,node_pipeline_models,node_pipeline_cache,node_pipeline_kinematics,node_backend_build,node_backend_geometry,node_backend_models,node_backend_cache,node_backend_kinematics,node_user toneBlue
class node_scene_viewer,node_scene_engine,node_motion_planner,node_incident_spec,node_kinematics,node_ingest_ui,node_video_export toneAmber
class node_assistant_session,node_assistant_tools,node_scene_controller,node_mcp_server,node_system_prompt,node_voice_controller toneMint
class node_landing_site toneRose
```

## Components

### Scene reconstruction

- [Scene builder](https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/build.py): `pipeline/src/reconstruct/build.py`
- [Footage ingest](https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/steps/ingest.py): `pipeline/src/reconstruct/steps/ingest.py`
- [Geometry model](https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/geometry.py): `pipeline/src/reconstruct/geometry.py`
- [Scene models](https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/models.py): `pipeline/src/reconstruct/models.py`
- [Step cache](https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/steps/cache.py): `pipeline/src/reconstruct/steps/cache.py`
- [Track kinematics](https://github.com/aarnavkannan/sunhacks/blob/main/pipeline/src/reconstruct/steps/kinematics.py): `pipeline/src/reconstruct/steps/kinematics.py`
- [Backend builder](https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/build.py): `BackEnd/pipeline/src/reconstruct/build.py`
- [Backend geometry](https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/geometry.py): `BackEnd/pipeline/src/reconstruct/geometry.py`
- [Backend models](https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/models.py): `BackEnd/pipeline/src/reconstruct/models.py`
- [Backend cache](https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/steps/cache.py): `BackEnd/pipeline/src/reconstruct/steps/cache.py`
- [Backend kinematics](https://github.com/aarnavkannan/sunhacks/blob/main/BackEnd/pipeline/src/reconstruct/steps/kinematics.py): `BackEnd/pipeline/src/reconstruct/steps/kinematics.py`

### Desktop review

- [Scene viewer](https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/SceneViewer.tsx): `FrontEnd/app/src/SceneViewer.tsx`
- [Scene engine](https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/gemini/engine.ts): `FrontEnd/app/src/gemini/engine.ts`
- [Motion planner](https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/gemini/motion.ts): `FrontEnd/app/src/gemini/motion.ts`
- [Incident spec](https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/gemini/spec.ts): `FrontEnd/app/src/gemini/spec.ts`
- [Kinematics analysis](https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/kinematics/derive.ts): `FrontEnd/app/src/kinematics/derive.ts`
- [Video ingest](https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/lib/ingest.ts): `FrontEnd/app/src/lib/ingest.ts`
- [Video export](https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/lib/exportVideo.ts): `FrontEnd/app/src/lib/exportVideo.ts`

### Assistant and voice

- [Assistant session](https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/session.ts): `packages/assistant/src/session.ts`
- [Tool registry](https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/tools/registry.ts): `packages/assistant/src/tools/registry.ts`
- [Scene controller](https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/controller.ts): `packages/assistant/src/controller.ts`
- [MCP server](https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/mcp/server.ts): `packages/assistant/src/mcp/server.ts`
- [System prompt](https://github.com/aarnavkannan/sunhacks/blob/main/packages/assistant/src/prompt/system-prompt.ts): `packages/assistant/src/prompt/system-prompt.ts`
- [Voice controller](https://github.com/aarnavkannan/sunhacks/blob/main/FrontEnd/app/src/voice/controller.ts): `FrontEnd/app/src/voice/controller.ts`

### Product site

- [Landing site](https://github.com/aarnavkannan/sunhacks/blob/main/landing/src/App.tsx): `landing/src/App.tsx`

### Other components

- **Reviewer**

## Connections

- Scene builder → Footage ingest: uses ingest (evidence: `pipeline/src/reconstruct/build.py`)
- Scene builder → Geometry model: uses geometry (evidence: `pipeline/src/reconstruct/build.py`)
- Scene builder → Scene models: uses models (evidence: `pipeline/src/reconstruct/build.py`)
- Scene builder → Step cache: uses cache (evidence: `pipeline/src/reconstruct/build.py`)
- Scene builder → Track kinematics: uses kinematics (evidence: `pipeline/src/reconstruct/build.py`)
- Backend builder → Backend geometry: uses geometry (evidence: `BackEnd/pipeline/src/reconstruct/build.py`)
- Backend builder → Backend models: uses models (evidence: `BackEnd/pipeline/src/reconstruct/build.py`)
- Backend builder → Backend cache: uses cache (evidence: `BackEnd/pipeline/src/reconstruct/build.py`)
- Backend builder → Backend kinematics: uses kinematics (evidence: `BackEnd/pipeline/src/reconstruct/build.py`)
- Scene engine → Incident spec: resolves spec (evidence: `FrontEnd/app/src/gemini/engine.ts`)
- Scene engine → Motion planner: plans motion (evidence: `FrontEnd/app/src/gemini/engine.ts`)
- Scene engine → Incident spec: builds roads (evidence: `FrontEnd/app/src/gemini/engine.ts`)
- Assistant session → MCP server: starts server (evidence: `packages/assistant/src/session.ts`)
- Assistant session → Tool registry: calls tools (evidence: `packages/assistant/src/session.ts`)
- MCP server → Tool registry: dispatches tools (evidence: `packages/assistant/src/mcp/server.ts`)
- Tool registry → Scene controller: invokes methods (evidence: `packages/assistant/src/tools/registry.ts`)
- Reviewer → Landing site: visits
