# yuragb/front_cam_detect architecture

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

- Interactive diagram: https://gitdiagram.com/yuragb/front_cam_detect
- Repository: https://github.com/yuragb/front_cam_detect

## Overview

#### Purpose and Entry Points
`cam_frontend` is a browser frontend for live camera monitoring. It negotiates WebRTC with a C++ camera service through a Bun signaling server, renders H264 tracks, overlays YOLO detections, and shows latency/pipeline metrics. The client bootstraps through TanStack Start routing in `src/router.tsx`, generated route definitions in `src/routeTree.gen.ts`, and root layout/provider composition in `src/routes/__root.tsx`.

#### Routing, Access, and Shell
Public routes include the home page and auth API; authenticated application pages are grouped under a protected route layout. Route-level protection and session retrieval form the boundary before dashboard, profile, address, and video pages render.
- `src/routes/(protected)/route.tsx`
- `src/routes/(protected)/video_stream/index.tsx`
- `src/lib/authBeforeLoad.ts`

The reusable application shell combines header, sidebar, locale/theme controls, and responsive UI components.
- `src/components/Header/Header.tsx`
- `src/modules/Sidebar/index.tsx`
- `src/components/SidebarWrapper.tsx`

#### Authentication and Persistence
Better Auth serves through a catch-all API route and a server-side auth module. Auth configuration integrates with Drizzle-backed user/session schema and synchronization logic; the browser uses a dedicated Better Auth client and session hooks.
- `src/routes/api/auth/$.ts`
- `src/server/modules/Auth/auth.ts`
- `src/server/modules/db/schema/auth.ts`

Database initialization is centralized in Drizzle, with migrations applied through a server plugin.
- `src/server/modules/db/drizzle/index.ts`
- `src/server/plugins/migrations/index.ts`
- `drizzle/0000_motionless_mandarin.sql`

#### WebRTC Signaling and Session Control
The VideoStream module opens one WebSocket to the Bun signaling server, registers a frontend peer identity, joins the C++ camera peer, and exchanges SDP offers/answers plus ICE candidates. PeerConnection lifecycle, stream association, and signaling message handling are separated into hooks and connection utilities.
- `src/modules/VideoStream/hooks/useWebsocket.ts`
- `src/modules/VideoStream/hooks/usePc.ts`
- `src/modules/VideoStream/lib/websocketConnection.ts`

This is the primary external integration boundary: browser WebSocket signaling versus browser-native WebRTC media/DataChannel transport to the C++ camera service.

#### Stream Rendering and Detection Overlay
Received video tracks are managed per camera and rendered as native `<video>` media, with an adjacent canvas overlay. Track-map messages connect WebRTC media IDs to camera IDs; detection frames are parsed, retained, and painted without rebinding media `srcObject`.
- `src/modules/VideoStream/hooks/useStreams.ts`
- `src/modules/VideoStream/components/CameraStreamView.tsx`
- `src/modules/VideoStream/lib/detections.ts`

`src/modules/VideoStream/index.tsx` composes stream access, peer connection, detection, metric, and view state into the live-monitoring page.

#### Telemetry Pipeline
The C++ service sends detection, track-map, video-latency, and pipeline-metric payloads over the `detectionStream` DataChannel. Parsing routes payload types into specialized state. Latency uses service capture timestamps plus `requestVideoFrameCallback()` render timing, while pipeline metrics expose capture, encoding, inference, and dropped-frame health separately.
- `src/modules/VideoStream/hooks/useVideoLatencyMetrics.ts`
- `src/modules/VideoStream/hooks/usePipelineMetrics.ts`
- `src/modules/VideoStream/components/PipelineMetricsPanel.tsx`

#### Runtime and Deployment
The runtime is React with TanStack Start/Router, TanStack Query, Tailwind-based UI, Paraglide localization, Better Auth, and Drizzle. Health/readiness endpoints support orchestration.
- `src/routes/(probes)/health.ts`
- `src/routes/(probes)/ready.ts`
- `src/integrations/tanstack-query/root-provider.tsx`

Container deployment targets k3s with namespace, ConfigMap/secrets, persistent volume, Deployment, Service, and ingress manifests.
- `Dockerfile`
- `k3s/frontend-app-deployment.yaml`
- `k3s/ingress.yaml`

Main entry points: [`src/modules/VideoStream/hooks/usePc.ts`](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/usePc.ts) (WebRTC peer lifecycle), [`src/routes/(protected)/route.tsx`](https://github.com/yuragb/front_cam_detect/blob/master/src/routes/(protected)/route.tsx) (Protected routes), [`src/modules/VideoStream/lib/detections.ts`](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/lib/detections.ts) (Telemetry parsing), [`src/modules/VideoStream/index.tsx`](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/index.tsx) (Video stream page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser client"]
  node_router["TanStack router<br/>routing<br/>[router.tsx]"]
  node_root["Root providers<br/>app shell root<br/>[__root.tsx]"]
  node_protected["Protected routes<br/>route guard<br/>[route.tsx]"]
  node_auth_guard["Session guard<br/>auth utility<br/>[authBeforeLoad.ts]"]
  node_shell["Application shell<br/>responsive UI shell<br/>[SidebarWrapper.tsx]"]
  node_video_page["Video stream page<br/>protected page<br/>[index.tsx]"]
  node_signaling_hook["Signaling session<br/>WebSocket hook<br/>[useWebsocket.ts]"]
  node_peer_connection["WebRTC peer lifecycle<br/>PeerConnection hook<br/>[usePc.ts]"]
  node_stream_state["Camera stream state<br/>track manager<br/>[useStreams.ts]"]
  node_camera_view["Camera video and overlay<br/>media renderer"]
  node_telemetry["Telemetry parsing<br/>detection parser<br/>[detections.ts]"]
  node_latency["Video latency metrics<br/>render metric hook"]
  node_pipeline_metrics["Pipeline metrics<br/>metric hook"]
  node_metrics_panel["Metrics panel<br/>monitoring UI"]
end

subgraph group_server["Application server"]
  node_auth_api["Better Auth API<br/>catch-all API route<br/>[$.ts]"]
  node_auth_server["Auth service<br/>server auth module<br/>[auth.ts]"]
  node_database[("User and session database<br/>Drizzle persistence<br/>[index.ts]")]
  node_probes["Health and readiness<br/>orchestration endpoints<br/>[health.ts]"]
end

subgraph group_camera["Camera integration"]
  node_signaling_server{{"Bun signaling server<br/>external signaling service"}}
  node_camera_service{{"C++ camera service<br/>external media service"}}
end

subgraph group_deploy["Deployment"]
  node_container["Frontend container<br/>Docker image"]
  node_k3s["k3s deployment<br/>Kubernetes workload"]
end

node_router -->|"mounts"| node_root
node_root -->|"hosts"| node_protected
node_protected -->|"checks session"| node_auth_guard
node_protected -->|"renders within"| node_shell
node_protected -->|"allows access"| node_video_page
node_video_page -->|"opens"| node_signaling_hook
node_video_page -->|"controls"| node_peer_connection
node_signaling_hook -->|"WebSocket SDP and ICE"| node_signaling_server
node_peer_connection -->|"WebRTC media and DataChannel"| node_camera_service
node_signaling_hook -->|"feeds negotiation"| node_peer_connection
node_peer_connection -->|"received tracks"| node_stream_state
node_stream_state -->|"camera media"| node_camera_view
node_peer_connection -->|"detectionStream payloads"| node_telemetry
node_telemetry -->|"detection overlay"| node_camera_view
node_telemetry -->|"capture timestamps"| node_latency
node_telemetry -->|"pipeline payloads"| node_pipeline_metrics
node_pipeline_metrics -->|"health metrics"| node_metrics_panel
node_latency -->|"latency metric"| node_metrics_panel
node_auth_api -->|"delegates"| node_auth_server
node_auth_server -->|"users and sessions"| node_database
node_container -->|"deployed by"| node_k3s

click node_router "https://github.com/yuragb/front_cam_detect/blob/master/src/router.tsx"
click node_root "https://github.com/yuragb/front_cam_detect/blob/master/src/routes/__root.tsx"
click node_protected "https://github.com/yuragb/front_cam_detect/blob/master/src/routes/(protected)/route.tsx"
click node_auth_guard "https://github.com/yuragb/front_cam_detect/blob/master/src/lib/authBeforeLoad.ts"
click node_shell "https://github.com/yuragb/front_cam_detect/blob/master/src/components/SidebarWrapper.tsx"
click node_video_page "https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/index.tsx"
click node_signaling_hook "https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/useWebsocket.ts"
click node_peer_connection "https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/usePc.ts"
click node_stream_state "https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/useStreams.ts"
click node_camera_view "https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/components/CameraStreamView.tsx"
click node_telemetry "https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/lib/detections.ts"
click node_latency "https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/useVideoLatencyMetrics.ts"
click node_pipeline_metrics "https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/usePipelineMetrics.ts"
click node_metrics_panel "https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/components/PipelineMetricsPanel.tsx"
click node_auth_api "https://github.com/yuragb/front_cam_detect/blob/master/src/routes/api/auth/%24.ts"
click node_auth_server "https://github.com/yuragb/front_cam_detect/blob/master/src/server/modules/Auth/auth.ts"
click node_database "https://github.com/yuragb/front_cam_detect/blob/master/src/server/modules/db/drizzle/index.ts"
click node_probes "https://github.com/yuragb/front_cam_detect/blob/master/src/routes/(probes)/health.ts"
click node_container "https://github.com/yuragb/front_cam_detect/blob/master/Dockerfile"
click node_k3s "https://github.com/yuragb/front_cam_detect/blob/master/k3s/frontend-app-deployment.yaml"

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_router,node_root,node_protected,node_auth_guard,node_shell,node_video_page,node_signaling_hook,node_peer_connection,node_stream_state,node_camera_view,node_telemetry,node_latency,node_pipeline_metrics,node_metrics_panel toneBlue
class node_auth_api,node_auth_server,node_database,node_probes toneAmber
class node_signaling_server,node_camera_service toneMint
class node_container,node_k3s toneRose
```

## Components

### Browser client

React live-monitoring application.

- [TanStack router](https://github.com/yuragb/front_cam_detect/blob/master/src/router.tsx): routing · Bootstraps routes and generated route definitions. · `src/router.tsx`
- [Root providers](https://github.com/yuragb/front_cam_detect/blob/master/src/routes/__root.tsx): app shell root · Composes global layout and providers. · `src/routes/__root.tsx`
- [Protected routes](https://github.com/yuragb/front_cam_detect/blob/master/src/routes/(protected)/route.tsx): route guard · Retrieves sessions before application pages render. · `src/routes/(protected)/route.tsx`
- [Session guard](https://github.com/yuragb/front_cam_detect/blob/master/src/lib/authBeforeLoad.ts): auth utility · `src/lib/authBeforeLoad.ts`
- [Application shell](https://github.com/yuragb/front_cam_detect/blob/master/src/components/SidebarWrapper.tsx): responsive UI shell · Header, sidebar, locale, and theme controls. · `src/components/SidebarWrapper.tsx`
- [Video stream page](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/index.tsx): protected page · Composes monitoring state, controls, and views. · `src/modules/VideoStream/index.tsx`
- [Signaling session](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/useWebsocket.ts): WebSocket hook · Registers the frontend peer and exchanges signaling messages. · `src/modules/VideoStream/hooks/useWebsocket.ts`
- [WebRTC peer lifecycle](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/usePc.ts): PeerConnection hook · Manages media and DataChannel connections. · `src/modules/VideoStream/hooks/usePc.ts`
- [Camera stream state](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/useStreams.ts): track manager · Associates received media tracks with cameras. · `src/modules/VideoStream/hooks/useStreams.ts`
- [Camera video and overlay](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/components/CameraStreamView.tsx): media renderer · Renders native video with adjacent detection canvas. · `src/modules/VideoStream/components/CameraStreamView.tsx`
- [Telemetry parsing](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/lib/detections.ts): detection parser · Routes detection and track-map payloads into state. · `src/modules/VideoStream/lib/detections.ts`
- [Video latency metrics](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/useVideoLatencyMetrics.ts): render metric hook · Combines capture timestamps with rendered-frame timing. · `src/modules/VideoStream/hooks/useVideoLatencyMetrics.ts`
- [Pipeline metrics](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/hooks/usePipelineMetrics.ts): metric hook · Tracks capture, encoding, inference, and dropped frames. · `src/modules/VideoStream/hooks/usePipelineMetrics.ts`
- [Metrics panel](https://github.com/yuragb/front_cam_detect/blob/master/src/modules/VideoStream/components/PipelineMetricsPanel.tsx): monitoring UI · `src/modules/VideoStream/components/PipelineMetricsPanel.tsx`

### Application server

TanStack Start server routes and persistence.

- [Better Auth API](https://github.com/yuragb/front_cam_detect/blob/master/src/routes/api/auth/%24.ts): catch-all API route · `src/routes/api/auth/$.ts`
- [Auth service](https://github.com/yuragb/front_cam_detect/blob/master/src/server/modules/Auth/auth.ts): server auth module · Configures Better Auth and schema synchronization. · `src/server/modules/Auth/auth.ts`
- [User and session database](https://github.com/yuragb/front_cam_detect/blob/master/src/server/modules/db/drizzle/index.ts): Drizzle persistence · Auth schema with migration-managed storage. · `src/server/modules/db/drizzle/index.ts`
- [Health and readiness](https://github.com/yuragb/front_cam_detect/blob/master/src/routes/(probes)/health.ts): orchestration endpoints · `src/routes/(probes)/health.ts`

### Camera integration

External Bun signaling and C++ camera service.

- **Bun signaling server**: external signaling service · Relays SDP and ICE negotiation messages.
- **C++ camera service**: external media service · Provides H264 media and detection telemetry.

### Deployment

Container and k3s runtime resources.

- [Frontend container](https://github.com/yuragb/front_cam_detect/blob/master/Dockerfile): Docker image · `Dockerfile`
- [k3s deployment](https://github.com/yuragb/front_cam_detect/blob/master/k3s/frontend-app-deployment.yaml): Kubernetes workload · Deploys the frontend with service and ingress. · `k3s/frontend-app-deployment.yaml`

## Connections

- TanStack router → Root providers: mounts
- Root providers → Protected routes: hosts
- Protected routes → Session guard: checks session
- Protected routes → Application shell: renders within
- Protected routes → Video stream page: allows access
- Video stream page → Signaling session: opens
- Video stream page → WebRTC peer lifecycle: controls
- Signaling session → Bun signaling server: WebSocket SDP and ICE
- WebRTC peer lifecycle → C++ camera service: WebRTC media and DataChannel
- Signaling session → WebRTC peer lifecycle: feeds negotiation
- WebRTC peer lifecycle → Camera stream state: received tracks
- Camera stream state → Camera video and overlay: camera media
- WebRTC peer lifecycle → Telemetry parsing: detectionStream payloads
- Telemetry parsing → Camera video and overlay: detection overlay
- Telemetry parsing → Video latency metrics: capture timestamps
- Telemetry parsing → Pipeline metrics: pipeline payloads
- Pipeline metrics → Metrics panel: health metrics
- Video latency metrics → Metrics panel: latency metric
- Better Auth API → Auth service: delegates
- Auth service → User and session database: users and sessions
- Frontend container → k3s deployment: deployed by