# likhithr916/indoor-navigation architecture

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

- Interactive diagram: https://gitdiagram.com/likhithr916/indoor-navigation
- Repository: https://github.com/likhithr916/indoor-navigation

## Overview

This prototype turns a walkthrough video into a relative place graph, then supports photo-based localization and obstacle-aware routing to a chosen destination. The UI also exposes landmark detection, map editing and calibration. The legacy discovery path is distinct from the redesign’s timestamped preprocessing and oracle-only occupancy/A* slice; README notes that grid planning is not connected to generated maps. Backend endpoint orchestration is visible, but excerpts omit some endpoint bodies and frontend request details, so uncertain links are left out.

Main entry points: [`backend/main.py`](https://github.com/likhithr916/indoor-navigation/blob/main/backend/main.py) (FastAPI service), [`web/src/App.jsx`](https://github.com/likhithr916/indoor-navigation/blob/main/web/src/App.jsx) (Navigation app), [`backend/mapping/places.py`](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/places.py) (Place discovery), [`web/src/MapEditor.jsx`](https://github.com/likhithr916/indoor-navigation/blob/main/web/src/MapEditor.jsx) (Map editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Navigation UI"]
  node_app["Navigation app<br/>[App.jsx]"]
  node_editor["Map editor<br/>[MapEditor.jsx]"]
end

subgraph group_api["Backend API"]
  node_api_service["FastAPI service<br/>[main.py]"]
  node_mapdata["Demo map data<br/>[map_data.py]"]
  node_map_store[("Generated map files<br/>[main.py]")]
end

subgraph group_mapping["Video Mapping"]
  node_video_io["Video sampling<br/>[video_io.py]"]
  node_frame_extract["Frame extraction"]
  node_frame_filter["Frame filtering<br/>[frame_filter.py]"]
  node_keyframes["Adaptive keyframes<br/>[keyframes.py]"]
  node_places["Place discovery<br/>[places.py]"]
  node_features["ORB features<br/>[features.py]"]
  node_matching["ORB matching<br/>[matching.py]"]
  node_visual_map["Visual route map<br/>[visual_map.py]"]
  node_detector["YOLO detector<br/>[detection.py]"]
end

subgraph group_navigation["Localization &amp; Routing"]
  node_localization["Photo localization<br/>[localization.py]"]
  node_routing["Weighted routing<br/>[routing.py]"]
end

subgraph group_grid["Grid Research Slice"]
  node_reconstruction["Reconstruction contract<br/>[reconstruction.py]"]
  node_occupancy["Occupancy builder<br/>[occupancy.py]"]
  node_planner["Grid A* planner<br/>[planner.py]"]
end

node_visitor(("User"))
node_browser_camera(("Camera / photo"))

node_visitor -->|"uses"| node_app
node_app -->|"uploads video"| node_api_service
node_app -.->|"requests navigation"| node_api_service
node_app -->|"embeds editor"| node_editor
node_browser_camera -->|"supplies photo"| node_app
node_api_service -.->|"extracts frames"| node_frame_extract
node_frame_extract -->|"decodes video"| node_video_io
node_api_service -.->|"filters frames"| node_frame_filter
node_frame_filter -->|"selects keyframes"| node_keyframes
node_api_service -->|"discovers places"| node_places
node_places -->|"computes features"| node_features
node_places -->|"matches frames"| node_matching
node_api_service -->|"passes detector"| node_detector
node_api_service -->|"serves map image"| node_visual_map
node_places -.->|"persists graph"| node_map_store
node_api_service -->|"reads map files"| node_map_store
node_api_service -->|"localizes photo"| node_localization
node_localization -->|"matches references"| node_matching
node_api_service -->|"finds route"| node_routing
node_routing -->|"uses default graph"| node_mapdata
node_api_service -->|"serves demo map"| node_mapdata
node_reconstruction -->|"provides contract"| node_occupancy
node_visitor -.->|"edits map"| node_editor
node_editor -->|"requests discovery"| node_api_service
node_editor -->|"renames places"| node_api_service
node_occupancy -.->|"plans grid route"| node_planner

click node_app "https://github.com/likhithr916/indoor-navigation/blob/main/web/src/App.jsx"
click node_editor "https://github.com/likhithr916/indoor-navigation/blob/main/web/src/MapEditor.jsx"
click node_api_service "https://github.com/likhithr916/indoor-navigation/blob/main/backend/main.py"
click node_mapdata "https://github.com/likhithr916/indoor-navigation/blob/main/backend/map_data.py"
click node_video_io "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/video_io.py"
click node_frame_extract "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/frame_extraction.py"
click node_frame_filter "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/frame_filter.py"
click node_keyframes "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/keyframes.py"
click node_places "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/places.py"
click node_features "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/features.py"
click node_matching "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/matching.py"
click node_visual_map "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/visual_map.py"
click node_detector "https://github.com/likhithr916/indoor-navigation/blob/main/backend/detection.py"
click node_localization "https://github.com/likhithr916/indoor-navigation/blob/main/backend/localization.py"
click node_routing "https://github.com/likhithr916/indoor-navigation/blob/main/backend/routing.py"
click node_reconstruction "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/reconstruction.py"
click node_occupancy "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/occupancy.py"
click node_planner "https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/planner.py"
click node_map_store "https://github.com/likhithr916/indoor-navigation/blob/main/backend/main.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_app,node_editor,node_visitor toneBlue
class node_api_service,node_mapdata,node_map_store toneAmber
class node_video_io,node_frame_extract,node_frame_filter,node_keyframes,node_places,node_features,node_matching,node_visual_map,node_detector toneMint
class node_localization,node_routing toneRose
class node_reconstruction,node_occupancy,node_planner,node_browser_camera toneIndigo
```

## Components

### Navigation UI

- [Navigation app](https://github.com/likhithr916/indoor-navigation/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Map editor](https://github.com/likhithr916/indoor-navigation/blob/main/web/src/MapEditor.jsx): `web/src/MapEditor.jsx`

### Backend API

- [FastAPI service](https://github.com/likhithr916/indoor-navigation/blob/main/backend/main.py): `backend/main.py`
- [Demo map data](https://github.com/likhithr916/indoor-navigation/blob/main/backend/map_data.py): `backend/map_data.py`
- [Generated map files](https://github.com/likhithr916/indoor-navigation/blob/main/backend/main.py): `backend/main.py`

### Video Mapping

- [Video sampling](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/video_io.py): `backend/mapping/video_io.py`
- [Frame extraction](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/frame_extraction.py): `backend/mapping/frame_extraction.py`
- [Frame filtering](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/frame_filter.py): `backend/mapping/frame_filter.py`
- [Adaptive keyframes](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/keyframes.py): `backend/mapping/keyframes.py`
- [Place discovery](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/places.py): `backend/mapping/places.py`
- [ORB features](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/features.py): `backend/mapping/features.py`
- [ORB matching](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/matching.py): `backend/mapping/matching.py`
- [Visual route map](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/visual_map.py): `backend/mapping/visual_map.py`
- [YOLO detector](https://github.com/likhithr916/indoor-navigation/blob/main/backend/detection.py): `backend/detection.py`

### Localization & Routing

- [Photo localization](https://github.com/likhithr916/indoor-navigation/blob/main/backend/localization.py): `backend/localization.py`
- [Weighted routing](https://github.com/likhithr916/indoor-navigation/blob/main/backend/routing.py): `backend/routing.py`

### Grid Research Slice

- [Reconstruction contract](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/reconstruction.py): `backend/mapping/reconstruction.py`
- [Occupancy builder](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/occupancy.py): `backend/mapping/occupancy.py`
- [Grid A* planner](https://github.com/likhithr916/indoor-navigation/blob/main/backend/mapping/planner.py): `backend/mapping/planner.py`

### Other components

- **User**
- **Camera / photo**

## Connections

- User → Navigation app: uses (evidence: `README.md`)
- Navigation app → FastAPI service: uploads video (evidence: `README.md`)
- Navigation app → FastAPI service: requests navigation
- Navigation app → Map editor: embeds editor (evidence: `web/src/App.jsx`)
- Camera / photo → Navigation app: supplies photo (evidence: `web/src/App.jsx`)
- FastAPI service → Frame extraction: extracts frames (evidence: `backend/main.py`)
- Frame extraction → Video sampling: decodes video (evidence: `backend/mapping/frame_extraction.py`)
- FastAPI service → Frame filtering: filters frames (evidence: `backend/main.py`)
- Frame filtering → Adaptive keyframes: selects keyframes (evidence: `backend/mapping/frame_filter.py`)
- FastAPI service → Place discovery: discovers places (evidence: `backend/main.py`)
- Place discovery → ORB features: computes features (evidence: `backend/mapping/places.py`)
- Place discovery → ORB matching: matches frames (evidence: `backend/mapping/places.py`)
- FastAPI service → YOLO detector: passes detector (evidence: `backend/main.py`)
- FastAPI service → Visual route map: serves map image (evidence: `backend/main.py`)
- Place discovery → Generated map files: persists graph (evidence: `backend/main.py`)
- FastAPI service → Generated map files: reads map files (evidence: `backend/main.py`)
- FastAPI service → Photo localization: localizes photo (evidence: `backend/main.py`)
- Photo localization → ORB matching: matches references (evidence: `backend/localization.py`)
- FastAPI service → Weighted routing: finds route (evidence: `backend/main.py`)
- Weighted routing → Demo map data: uses default graph (evidence: `backend/routing.py`)
- FastAPI service → Demo map data: serves demo map (evidence: `backend/main.py`)
- Reconstruction contract → Occupancy builder: provides contract (evidence: `backend/mapping/occupancy.py`)
- User → Map editor: edits map
- Map editor → FastAPI service: requests discovery (evidence: `web/src/MapEditor.jsx`)
- Map editor → FastAPI service: renames places (evidence: `web/src/MapEditor.jsx`)
- Occupancy builder → Grid A* planner: plans grid route
