# eunseong-jo/expo-2026 architecture

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

- Interactive diagram: https://gitdiagram.com/eunseong-jo/expo-2026
- Repository: https://github.com/eunseong-jo/expo-2026

## Overview

VisionGuide combines a Raspberry Pi assistive-vision runtime with local ROI configuration and a networked management dashboard. The main path is camera frames through cane detection, tracking and ROI-trigger logic to spoken guidance; device events and status can also be managed and monitored through the FastAPI/React dashboard. README capabilities and the source index support the major branches shown. Several device and dashboard routes are unsampled, so their internal links are omitted rather than inferred.

Main entry points: [`device/camera_live_pi.py`](https://github.com/eunseong-jo/expo-2026/blob/main/device/camera_live_pi.py) (Runtime Orchestrator), [`dashboard/backend/app/main.py`](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/main.py) (API Application), [`apps/simulator/roi_manager.py`](https://github.com/eunseong-jo/expo-2026/blob/main/apps/simulator/roi_manager.py) (ROI Manager), [`dashboard/frontend/src/App.tsx`](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/frontend/src/App.tsx) (Dashboard Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["Pi Guidance Runtime"]
  node_pi["Runtime Orchestrator<br/>[camera_live_pi.py]"]
  node_inference["Cane Detection<br/>[detect.py]"]
  node_postprocess["YOLO Postprocess"]
  node_tracking["Object Tracking<br/>[simple_tracker.py]"]
  node_association["Cane Association"]
  node_gates["Trigger Gate Chain<br/>[gate_chain.py]"]
  node_announcer["Announcement Routing"]
  node_player["Audio Trigger Player<br/>[audio_trigger.py]"]
  node_eventlog["Event Logging<br/>[event_logger.py]"]
  node_replay["Video Replay<br/>[replay_engine.py]"]
end

subgraph group_local["Local Tools"]
  node_roi["ROI Manager<br/>[roi_manager.py]"]
  node_roi_editor["Pi ROI Editor<br/>[server.py]"]
  node_simulator["PC Simulator<br/>[app.py]"]
  node_network["Wi-Fi Onboarding<br/>[network_manager.py]"]
end

subgraph group_backend["Management Backend"]
  node_eventapi["Event Ingest API<br/>[events.py]"]
  node_db[("Dashboard Database<br/>[database.py]")]
  node_backend["API Application<br/>[main.py]"]
  node_heartbeat["Device Heartbeats"]
  node_deviceapi["Device Management API<br/>[devices.py]"]
  node_calibration["Calibration Services"]
  node_stats["Statistics Service<br/>[stats_service.py]"]
  node_ws["WebSocket Manager<br/>[ws_manager.py]"]
end

subgraph group_frontend["Web Dashboard"]
  node_app["Dashboard Routes<br/>[App.tsx]"]
  node_api["API Client<br/>[client.ts]"]
  node_detail["Device Detail UI<br/>[DeviceDetail.tsx]"]
end

node_user(("Blind Cane User"))
node_camera["Pi Camera"]
node_audio["Audio Output"]
node_browser(("Administrator"))

node_user -->|"enters view"| node_camera
node_camera -.->|"frames"| node_pi
node_pi -->|"runs inference"| node_inference
node_inference -.->|"postprocesses"| node_postprocess
node_pi -->|"tracks detections"| node_tracking
node_pi -->|"associates cane users"| node_association
node_pi -->|"evaluates gates"| node_gates
node_pi -->|"checks regions"| node_roi
node_pi -->|"routes announcements"| node_announcer
node_pi -->|"triggers audio"| node_player
node_player -->|"plays MP3"| node_audio
node_pi -->|"logs events"| node_eventlog
node_eventlog -.->|"posts events"| node_eventapi
node_backend -->|"registers router"| node_eventapi
node_backend -->|"registers router"| node_deviceapi
node_backend -.->|"initializes database"| node_db
node_heartbeat -->|"reads and writes"| node_db
node_stats -->|"queries records"| node_db
node_backend -.->|"schedules service"| node_heartbeat
node_browser -->|"uses dashboard"| node_app
node_app -.->|"loads data through"| node_api
node_api -.->|"HTTP requests"| node_backend
node_detail -->|"calls API"| node_api
node_app -->|"routes to"| node_detail
node_backend -.->|"broadcasts events"| node_ws
node_detail -.->|"configures calibration"| node_calibration
node_roi_editor -.->|"edits ROI settings"| node_roi
node_simulator -->|"uses ROI manager"| node_roi
node_replay -->|"builds inference backend"| node_pi
node_replay -->|"filters by ROI"| node_roi
node_roi_editor -.->|"uses network controls"| node_network

click node_pi "https://github.com/eunseong-jo/expo-2026/blob/main/device/camera_live_pi.py"
click node_inference "https://github.com/eunseong-jo/expo-2026/blob/main/device/detect.py"
click node_postprocess "https://github.com/eunseong-jo/expo-2026/blob/main/device/yolo_postprocess.py"
click node_tracking "https://github.com/eunseong-jo/expo-2026/blob/main/device/simple_tracker.py"
click node_association "https://github.com/eunseong-jo/expo-2026/blob/main/device/cane_person_assoc.py"
click node_gates "https://github.com/eunseong-jo/expo-2026/blob/main/device/gate_chain.py"
click node_roi "https://github.com/eunseong-jo/expo-2026/blob/main/apps/simulator/roi_manager.py"
click node_announcer "https://github.com/eunseong-jo/expo-2026/blob/main/device/announcement_router.py"
click node_player "https://github.com/eunseong-jo/expo-2026/blob/main/device/audio_trigger.py"
click node_eventlog "https://github.com/eunseong-jo/expo-2026/blob/main/device/event_logger.py"
click node_eventapi "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/routers/events.py"
click node_db "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/database.py"
click node_backend "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/main.py"
click node_heartbeat "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/services/heartbeat_service.py"
click node_deviceapi "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/routers/devices.py"
click node_calibration "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/services/calibration_service.py"
click node_stats "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/services/stats_service.py"
click node_ws "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/services/ws_manager.py"
click node_app "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/frontend/src/App.tsx"
click node_api "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/frontend/src/api/client.ts"
click node_detail "https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/frontend/src/pages/DeviceDetail.tsx"
click node_roi_editor "https://github.com/eunseong-jo/expo-2026/blob/main/apps/roi_editor/server.py"
click node_simulator "https://github.com/eunseong-jo/expo-2026/blob/main/apps/simulator/app.py"
click node_replay "https://github.com/eunseong-jo/expo-2026/blob/main/device/replay_engine.py"
click node_network "https://github.com/eunseong-jo/expo-2026/blob/main/apps/roi_editor/network_manager.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_pi,node_inference,node_postprocess,node_tracking,node_association,node_gates,node_announcer,node_player,node_eventlog,node_replay,node_user toneBlue
class node_roi,node_roi_editor,node_simulator,node_network toneAmber
class node_eventapi,node_db,node_backend,node_heartbeat,node_deviceapi,node_calibration,node_stats,node_ws toneMint
class node_app,node_api,node_detail toneRose
class node_camera,node_audio,node_browser toneIndigo
```

## Components

### Pi Guidance Runtime

- [Runtime Orchestrator](https://github.com/eunseong-jo/expo-2026/blob/main/device/camera_live_pi.py): `device/camera_live_pi.py`
- [Cane Detection](https://github.com/eunseong-jo/expo-2026/blob/main/device/detect.py): `device/detect.py`
- [YOLO Postprocess](https://github.com/eunseong-jo/expo-2026/blob/main/device/yolo_postprocess.py): `device/yolo_postprocess.py`
- [Object Tracking](https://github.com/eunseong-jo/expo-2026/blob/main/device/simple_tracker.py): `device/simple_tracker.py`
- [Cane Association](https://github.com/eunseong-jo/expo-2026/blob/main/device/cane_person_assoc.py): `device/cane_person_assoc.py`
- [Trigger Gate Chain](https://github.com/eunseong-jo/expo-2026/blob/main/device/gate_chain.py): `device/gate_chain.py`
- [Announcement Routing](https://github.com/eunseong-jo/expo-2026/blob/main/device/announcement_router.py): `device/announcement_router.py`
- [Audio Trigger Player](https://github.com/eunseong-jo/expo-2026/blob/main/device/audio_trigger.py): `device/audio_trigger.py`
- [Event Logging](https://github.com/eunseong-jo/expo-2026/blob/main/device/event_logger.py): `device/event_logger.py`
- [Video Replay](https://github.com/eunseong-jo/expo-2026/blob/main/device/replay_engine.py): `device/replay_engine.py`

### Local Tools

- [ROI Manager](https://github.com/eunseong-jo/expo-2026/blob/main/apps/simulator/roi_manager.py): `apps/simulator/roi_manager.py`
- [Pi ROI Editor](https://github.com/eunseong-jo/expo-2026/blob/main/apps/roi_editor/server.py): `apps/roi_editor/server.py`
- [PC Simulator](https://github.com/eunseong-jo/expo-2026/blob/main/apps/simulator/app.py): `apps/simulator/app.py`
- [Wi-Fi Onboarding](https://github.com/eunseong-jo/expo-2026/blob/main/apps/roi_editor/network_manager.py): `apps/roi_editor/network_manager.py`

### Management Backend

- [Event Ingest API](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/routers/events.py): `dashboard/backend/app/routers/events.py`
- [Dashboard Database](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/database.py): `dashboard/backend/app/database.py`
- [API Application](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/main.py): `dashboard/backend/app/main.py`
- [Device Heartbeats](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/services/heartbeat_service.py): `dashboard/backend/app/services/heartbeat_service.py`
- [Device Management API](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/routers/devices.py): `dashboard/backend/app/routers/devices.py`
- [Calibration Services](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/services/calibration_service.py): `dashboard/backend/app/services/calibration_service.py`
- [Statistics Service](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/services/stats_service.py): `dashboard/backend/app/services/stats_service.py`
- [WebSocket Manager](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/backend/app/services/ws_manager.py): `dashboard/backend/app/services/ws_manager.py`

### Web Dashboard

- [Dashboard Routes](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/frontend/src/App.tsx): `dashboard/frontend/src/App.tsx`
- [API Client](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/frontend/src/api/client.ts): `dashboard/frontend/src/api/client.ts`
- [Device Detail UI](https://github.com/eunseong-jo/expo-2026/blob/main/dashboard/frontend/src/pages/DeviceDetail.tsx): `dashboard/frontend/src/pages/DeviceDetail.tsx`

### Other components

- **Blind Cane User**
- **Pi Camera**
- **Audio Output**
- **Administrator**

## Connections

- Blind Cane User → Pi Camera: enters view
- Pi Camera → Runtime Orchestrator: frames
- Runtime Orchestrator → Cane Detection: runs inference (evidence: `device/camera_live_pi.py`)
- Cane Detection → YOLO Postprocess: postprocesses
- Runtime Orchestrator → Object Tracking: tracks detections (evidence: `device/camera_live_pi.py`)
- Runtime Orchestrator → Cane Association: associates cane users (evidence: `device/camera_live_pi.py`)
- Runtime Orchestrator → Trigger Gate Chain: evaluates gates (evidence: `device/camera_live_pi.py`)
- Runtime Orchestrator → ROI Manager: checks regions (evidence: `device/camera_live_pi.py`)
- Runtime Orchestrator → Announcement Routing: routes announcements (evidence: `device/camera_live_pi.py`)
- Runtime Orchestrator → Audio Trigger Player: triggers audio (evidence: `device/camera_live_pi.py`)
- Audio Trigger Player → Audio Output: plays MP3
- Runtime Orchestrator → Event Logging: logs events (evidence: `device/camera_live_pi.py`)
- Event Logging → Event Ingest API: posts events
- API Application → Event Ingest API: registers router (evidence: `dashboard/backend/app/main.py`)
- API Application → Device Management API: registers router (evidence: `dashboard/backend/app/main.py`)
- API Application → Dashboard Database: initializes database (evidence: `dashboard/backend/app/main.py`)
- Device Heartbeats → Dashboard Database: reads and writes (evidence: `dashboard/backend/app/services/heartbeat_service.py`)
- Statistics Service → Dashboard Database: queries records (evidence: `dashboard/backend/app/services/stats_service.py`)
- API Application → Device Heartbeats: schedules service (evidence: `dashboard/backend/app/main.py`)
- Administrator → Dashboard Routes: uses dashboard
- Dashboard Routes → API Client: loads data through
- API Client → API Application: HTTP requests
- Device Detail UI → API Client: calls API (evidence: `dashboard/frontend/src/pages/DeviceDetail.tsx`)
- Dashboard Routes → Device Detail UI: routes to (evidence: `dashboard/frontend/src/App.tsx`)
- API Application → WebSocket Manager: broadcasts events
- Device Detail UI → Calibration Services: configures calibration
- Pi ROI Editor → ROI Manager: edits ROI settings (evidence: `apps/roi_editor/server.py`)
- PC Simulator → ROI Manager: uses ROI manager (evidence: `apps/simulator/app.py`)
- Video Replay → Runtime Orchestrator: builds inference backend (evidence: `device/replay_engine.py`)
- Video Replay → ROI Manager: filters by ROI (evidence: `device/replay_engine.py`)
- Pi ROI Editor → Wi-Fi Onboarding: uses network controls (evidence: `apps/roi_editor/server.py`)