# pawankus6261/tracker architecture

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

- Interactive diagram: https://gitdiagram.com/pawankus6261/tracker
- Repository: https://github.com/pawankus6261/tracker

## Overview

This is a live location-tracking product: a session owner creates a shareable link, a device explicitly grants GPS access and sends fixes, and an owner dashboard receives telemetry and displays the accepted route. The backend validates and processes fixes, classifies quality and outliers, persists session history, and broadcasts updates. The README documents map, stale-fix, accuracy, and sharing capabilities; sampled excerpts confirm the core backend processing and WebSocket dispatch. Frontend wiring beyond the supplied excerpts is represented only where supported by the README or file structure.

Main entry points: [`frontend/src/pages/Dashboard.jsx`](https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/Dashboard.jsx) (Owner dashboard), [`backend/app/routes/sessions.py`](https://github.com/pawankus6261/tracker/blob/main/backend/app/routes/sessions.py) (Session and socket routes), [`frontend/src/pages/CreateSession.jsx`](https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/CreateSession.jsx) (Create and share), [`frontend/src/pages/TrackingSession.jsx`](https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/TrackingSession.jsx) (Device tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Tracking interface"]
  node_app["Route selection<br/>[App.jsx]"]
  node_create["Create and share<br/>[CreateSession.jsx]"]
  node_dashboard["Owner dashboard<br/>[Dashboard.jsx]"]
  node_public["Public tracking page<br/>[PublicTracking.jsx]"]
  node_tracking["Device tracking"]
  node_permission["Location permission"]
  node_map["Live map and trail<br/>[MapView.jsx]"]
  node_status["Status and accuracy<br/>[TrackingStatus.jsx]"]
  node_controls["Tracking controls"]
  node_share["Share link modal<br/>[ShareLinkModal.jsx]"]
  node_geo_client["Browser geolocation<br/>[geolocation.js]"]
  node_ws_client["WebSocket client<br/>[websocket.js]"]
end

subgraph group_api["Session API"]
  node_api_client["HTTP API client<br/>[api.js]"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_routes["Session and socket routes<br/>[sessions.py]"]
  node_schemas["Request and response schemas<br/>[session.py]"]
end

subgraph group_processing["Telemetry processing"]
  node_tracking_service["Fix processing"]
  node_location_service["Quality and location services"]
  node_ws_manager["Connection manager<br/>[manager.py]"]
end

subgraph group_state["Tracking state"]
  node_database["Database access<br/>[database.py]"]
  node_session_model[("Tracking sessions")]
  node_point_model[("Location history<br/>[location_point.py]")]
end

subgraph group_integrations["External services"]
  node_maptiler{{"MapTiler tiles and geocoding"}}
  node_geo_providers{{"Geocoding and elevation providers"}}
  node_qr_service{{"QR code service"}}
end

node_owner(("Session owner"))
node_device(("Tracking device"))
node_browser_gps(("Device GPS"))

node_owner -->|"opens app"| node_app
node_app -->|"routes home"| node_create
node_app -->|"routes dashboard"| node_dashboard
node_app -->|"routes tracking link"| node_public
node_owner -->|"requests session"| node_create
node_create -->|"creates session"| node_api_client
node_api_client -->|"HTTP requests"| node_backend
node_backend -->|"mounts routes"| node_routes
node_routes -->|"validates and shapes"| node_schemas
node_routes -->|"reads and writes"| node_database
node_database -->|"persists"| node_session_model
node_database -->|"persists"| node_point_model
node_owner -->|"views session"| node_dashboard
node_dashboard -->|"loads session"| node_api_client
node_dashboard -->|"subscribes telemetry"| node_ws_client
node_public -->|"validates link"| node_api_client
node_public -->|"opens device flow"| node_tracking
node_device -->|"opens tracking link"| node_tracking
node_tracking -->|"requests consent"| node_permission
node_permission -->|"starts location"| node_geo_client
node_geo_client -->|"requests GPS fixes"| node_browser_gps
node_tracking -->|"sends fixes"| node_ws_client
node_ws_client -->|"device WebSocket"| node_routes
node_routes -->|"processes fix"| node_tracking_service
node_tracking_service -->|"classifies and enriches"| node_location_service
node_tracking_service -->|"stores fix and state"| node_database
node_routes -->|"dispatches telemetry"| node_ws_manager
node_ws_manager -->|"broadcasts updates"| node_ws_client
node_ws_client -->|"delivers telemetry"| node_dashboard
node_dashboard -->|"renders positions"| node_map
node_dashboard -->|"shows telemetry status"| node_status
node_tracking -->|"provides tracking controls"| node_controls
node_create -->|"offers sharing"| node_share
node_map -.->|"loads map tiles"| node_maptiler
node_create -.->|"requests QR image"| node_qr_service
node_location_service -.->|"resolves address and elevation"| node_geo_providers

click node_app "https://github.com/pawankus6261/tracker/blob/main/frontend/src/App.jsx"
click node_create "https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/CreateSession.jsx"
click node_dashboard "https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/Dashboard.jsx"
click node_public "https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/PublicTracking.jsx"
click node_tracking "https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/TrackingSession.jsx"
click node_permission "https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/LocationPermission.jsx"
click node_map "https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/MapView.jsx"
click node_status "https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/TrackingStatus.jsx"
click node_controls "https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/TrackingControls.jsx"
click node_share "https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/ShareLinkModal.jsx"
click node_api_client "https://github.com/pawankus6261/tracker/blob/main/frontend/src/services/api.js"
click node_geo_client "https://github.com/pawankus6261/tracker/blob/main/frontend/src/services/geolocation.js"
click node_ws_client "https://github.com/pawankus6261/tracker/blob/main/frontend/src/services/websocket.js"
click node_backend "https://github.com/pawankus6261/tracker/blob/main/backend/app/main.py"
click node_routes "https://github.com/pawankus6261/tracker/blob/main/backend/app/routes/sessions.py"
click node_schemas "https://github.com/pawankus6261/tracker/blob/main/backend/app/schemas/session.py"
click node_tracking_service "https://github.com/pawankus6261/tracker/blob/main/backend/app/services/tracking_service.py"
click node_location_service "https://github.com/pawankus6261/tracker/blob/main/backend/app/services/location_service.py"
click node_ws_manager "https://github.com/pawankus6261/tracker/blob/main/backend/app/websocket/manager.py"
click node_database "https://github.com/pawankus6261/tracker/blob/main/backend/app/database.py"
click node_session_model "https://github.com/pawankus6261/tracker/blob/main/backend/app/models/tracking_session.py"
click node_point_model "https://github.com/pawankus6261/tracker/blob/main/backend/app/models/location_point.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_create,node_dashboard,node_public,node_tracking,node_permission,node_map,node_status,node_controls,node_share,node_geo_client,node_ws_client toneBlue
class node_api_client,node_backend,node_routes,node_schemas toneAmber
class node_tracking_service,node_location_service,node_ws_manager toneMint
class node_database,node_session_model,node_point_model toneRose
class node_maptiler,node_geo_providers,node_qr_service,node_owner,node_device,node_browser_gps toneIndigo
```

## Components

### Tracking interface

- [Route selection](https://github.com/pawankus6261/tracker/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Create and share](https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/CreateSession.jsx): `frontend/src/pages/CreateSession.jsx`
- [Owner dashboard](https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Public tracking page](https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/PublicTracking.jsx): `frontend/src/pages/PublicTracking.jsx`
- [Device tracking](https://github.com/pawankus6261/tracker/blob/main/frontend/src/pages/TrackingSession.jsx): `frontend/src/pages/TrackingSession.jsx`
- [Location permission](https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/LocationPermission.jsx): `frontend/src/components/LocationPermission.jsx`
- [Live map and trail](https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/MapView.jsx): `frontend/src/components/MapView.jsx`
- [Status and accuracy](https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/TrackingStatus.jsx): `frontend/src/components/TrackingStatus.jsx`
- [Tracking controls](https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/TrackingControls.jsx): `frontend/src/components/TrackingControls.jsx`
- [Share link modal](https://github.com/pawankus6261/tracker/blob/main/frontend/src/components/ShareLinkModal.jsx): `frontend/src/components/ShareLinkModal.jsx`
- [Browser geolocation](https://github.com/pawankus6261/tracker/blob/main/frontend/src/services/geolocation.js): `frontend/src/services/geolocation.js`
- [WebSocket client](https://github.com/pawankus6261/tracker/blob/main/frontend/src/services/websocket.js): `frontend/src/services/websocket.js`

### Session API

- [HTTP API client](https://github.com/pawankus6261/tracker/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [FastAPI application](https://github.com/pawankus6261/tracker/blob/main/backend/app/main.py): `backend/app/main.py`
- [Session and socket routes](https://github.com/pawankus6261/tracker/blob/main/backend/app/routes/sessions.py): `backend/app/routes/sessions.py`
- [Request and response schemas](https://github.com/pawankus6261/tracker/blob/main/backend/app/schemas/session.py): `backend/app/schemas/session.py`

### Telemetry processing

- [Fix processing](https://github.com/pawankus6261/tracker/blob/main/backend/app/services/tracking_service.py): `backend/app/services/tracking_service.py`
- [Quality and location services](https://github.com/pawankus6261/tracker/blob/main/backend/app/services/location_service.py): `backend/app/services/location_service.py`
- [Connection manager](https://github.com/pawankus6261/tracker/blob/main/backend/app/websocket/manager.py): `backend/app/websocket/manager.py`

### Tracking state

- [Database access](https://github.com/pawankus6261/tracker/blob/main/backend/app/database.py): `backend/app/database.py`
- [Tracking sessions](https://github.com/pawankus6261/tracker/blob/main/backend/app/models/tracking_session.py): `backend/app/models/tracking_session.py`
- [Location history](https://github.com/pawankus6261/tracker/blob/main/backend/app/models/location_point.py): `backend/app/models/location_point.py`

### External services

- **MapTiler tiles and geocoding**
- **Geocoding and elevation providers**
- **QR code service**

### Other components

- **Session owner**
- **Tracking device**
- **Device GPS**

## Connections

- Session owner → Route selection: opens app
- Route selection → Create and share: routes home
- Route selection → Owner dashboard: routes dashboard
- Route selection → Public tracking page: routes tracking link
- Session owner → Create and share: requests session
- Create and share → HTTP API client: creates session
- HTTP API client → FastAPI application: HTTP requests
- FastAPI application → Session and socket routes: mounts routes
- Session and socket routes → Request and response schemas: validates and shapes
- Session and socket routes → Database access: reads and writes
- Database access → Tracking sessions: persists
- Database access → Location history: persists
- Session owner → Owner dashboard: views session
- Owner dashboard → HTTP API client: loads session
- Owner dashboard → WebSocket client: subscribes telemetry
- Public tracking page → HTTP API client: validates link
- Public tracking page → Device tracking: opens device flow
- Tracking device → Device tracking: opens tracking link
- Device tracking → Location permission: requests consent
- Location permission → Browser geolocation: starts location
- Browser geolocation → Device GPS: requests GPS fixes
- Device tracking → WebSocket client: sends fixes
- WebSocket client → Session and socket routes: device WebSocket
- Session and socket routes → Fix processing: processes fix
- Fix processing → Quality and location services: classifies and enriches
- Fix processing → Database access: stores fix and state
- Session and socket routes → Connection manager: dispatches telemetry
- Connection manager → WebSocket client: broadcasts updates
- WebSocket client → Owner dashboard: delivers telemetry
- Owner dashboard → Live map and trail: renders positions
- Owner dashboard → Status and accuracy: shows telemetry status
- Device tracking → Tracking controls: provides tracking controls
- Create and share → Share link modal: offers sharing
- Live map and trail → MapTiler tiles and geocoding: loads map tiles
- Create and share → QR code service: requests QR image
- Quality and location services → Geocoding and elevation providers: resolves address and elevation