# yuragb/server_for_cam_det architecture

> Architecture diagram of the GitHub repository yuragb/server_for_cam_det, 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/server_for_cam_det
- Repository: https://github.com/yuragb/server_for_cam_det

## Overview

#### Purpose and Entry Points
`cam_serv` is a Bun/Elysia WebRTC signaling service. It authenticates WebSocket upgrades, tracks connected peers, and relays SDP/ICE-style signaling payloads between peers; it does not carry media. Process startup is centered on `src/server.ts`, with application composition in `src/Elysia/app.ts` and Elysia bootstrap/export in `src/Elysia/index.ts`.

#### HTTP and WebSocket Surface
The route layer exposes root/health endpoints and the `/ws` signaling endpoint through `src/Elysia/modules/Routes/index.ts` and `src/Elysia/modules/Routes/Signals/index.ts`. WebSocket configuration, lifecycle handling, peer registration, forwarding, heartbeat cleanup, and connection limits are concentrated in:
- `src/Elysia/modules/websockets/index.ts`
- `src/Elysia/modules/websockets/websocketConfig.ts`
- `src/Elysia/modules/websockets/wsLimits.ts`

Control flow is: upgrade request → authenticate → connect socket → require `register` with `peerId` → map peer ID to socket → forward validated messages to `targetPeerId` with sender identity → remove peers on close/heartbeat expiry. Duplicate peer IDs replace the earlier connection.

#### Authentication and Request Security
JWT validation is applied at the Elysia module boundary, supporting bearer tokens and browser query-token fallback. Authentication components are:
- `src/Elysia/modules/Authentication/index.ts`
- `src/Elysia/modules/Authentication/utils/index.ts`
- `src/Elysia/modules/Security/Cooclie/index.ts`

Tokens may be validated via frontend-auth JWKS or shared-secret service JWTs, using issuer/audience and service-issuer environment configuration. Cross-cutting HTTP/security controls include rate limiting and security headers:
- `src/Elysia/modules/Security/RateLimiter/index.ts`
- `src/Elysia/modules/Security/SecurityHeaders/index.ts`

#### State, Persistence, and Cache Boundaries
Live signaling-peer state is inherently process-local WebSocket state. Redis is provisioned as infrastructure and is represented in application/cache modules:
- `src/Redis/index.ts`
- `src/Elysia/modules/infrastructure/cache/cache.service.ts`
- `k3s/05-signaling-redis-deployment.yaml`

SQLite/Drizzle persistence also exists, including a shallow-user schema and versioned migrations:
- `src/db/drizzle/index.ts`
- `src/db/schema/ShalowUsers.ts`
- `drizzle/0001_lush_morlocks.sql`

This separates transient connection routing from durable user-oriented data.

#### Runtime and Deployment
The service runs on Bun with Elysia, containerized by `Dockerfile`. It can run locally with Docker Compose or on k3s. Kubernetes manifests deploy separate signaling-app and Redis workloads, persistent volumes, services, secrets/config maps, and ingress:
- `docker-compose.yml`
- `k3s/05-signaling-app-deployment.yaml`
- `k3s/09-ingress.yaml`

Environment-driven limits include port, log level, maximum signaling-message bytes, JWT secret, issuer, audience, and allowed service issuers. `/health` supports probes and reports connected-peer state.

#### Supporting Service Boundaries
User synchronization is represented separately from realtime signaling:
- `src/Elysia/modules/Routes/User/index.ts`
- `src/Elysia/modules/Routes/User/Controllers/sync.controller.ts`
- `src/Elysia/modules/Routes/User/Services/index.ts`

`src/cluster.ts` indicates process/cluster orchestration as a runtime concern. Any scaling design must preserve peer-routing correctness: a sender and target located on different app instances need shared routing/session coordination, for which Redis is the likely infrastructure boundary.

Main entry points: [`src/Elysia/app.ts`](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/app.ts) (Application composition), [`src/Elysia/modules/websockets/index.ts`](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/websockets/index.ts) (Peer signaling lifecycle), [`src/Elysia/modules/Routes/index.ts`](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/index.ts) (HTTP routes), [`src/Elysia/modules/Routes/Signals/index.ts`](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/Signals/index.ts) (Signaling endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Bun / Elysia service"]
  node_server["Process startup<br/>Bun entrypoint<br/>[server.ts]"]
  node_elysia_index["Elysia bootstrap<br/>app export<br/>[index.ts]"]
  node_elysia_app["Application composition<br/>Elysia app<br/>[app.ts]"]
  node_routes["HTTP routes<br/>route module<br/>[index.ts]"]
  node_signals["Signaling endpoint<br/>WebSocket route<br/>[index.ts]"]
  node_websockets["Peer signaling lifecycle<br/>WebSocket service<br/>[index.ts]"]
  node_ws_config["Socket configuration<br/>WebSocket config<br/>[websocketConfig.ts]"]
  node_ws_limits["Connection limits<br/>WebSocket limits<br/>[wsLimits.ts]"]
  node_authentication{{"JWT authentication<br/>auth boundary<br/>[index.ts]"}}
  node_auth_utils["JWT validators<br/>auth utilities<br/>[index.ts]"]
  node_cookie_security["Cookie security<br/>security module<br/>[index.ts]"]
  node_rate_limiter["Rate limiting<br/>security middleware<br/>[index.ts]"]
  node_security_headers["Security headers<br/>security middleware<br/>[index.ts]"]
  node_user_sync["User synchronization<br/>user API<br/>[index.ts]"]
  node_user_sync_controller["Sync controller<br/>[sync.controller.ts]"]
  node_user_services["User services<br/>service layer<br/>[index.ts]"]
  node_cluster["Cluster orchestration<br/>runtime orchestration<br/>[cluster.ts]"]
end

subgraph group_state["State and persistence"]
  node_redis_cache[("Redis cache boundary<br/>cache module<br/>[index.ts]")]
  node_cache_service["Cache service<br/>cache adapter<br/>[cache.service.ts]"]
  node_drizzle[("Drizzle persistence<br/>database layer<br/>[index.ts]")]
  node_user_schema["Shallow users schema<br/>database schema<br/>[ShalowUsers.ts]"]
  node_migration["Initial migration<br/>SQL migration"]
end

subgraph group_deploy["Container and k3s"]
  node_container["Container image<br/>Docker build"]
  node_compose["Local stack<br/>Docker Compose<br/>[docker-compose.yml]"]
  node_signaling_deployment{{"Signaling app workload<br/>k3s deployment"}}
  node_redis_deployment[("Redis workload<br/>k3s deployment")]
  node_ingress{{"Ingress<br/>[09-ingress.yaml]"}}
end

node_server -->|"starts"| node_elysia_index
node_elysia_index -->|"exports"| node_elysia_app
node_elysia_app -->|"mounts"| node_routes
node_elysia_app -->|"applies"| node_authentication
node_elysia_app -->|"applies"| node_rate_limiter
node_elysia_app -->|"applies"| node_security_headers
node_elysia_app -->|"applies"| node_cookie_security
node_routes -->|"routes /ws"| node_signals
node_routes -->|"routes user sync"| node_user_sync
node_authentication -->|"validates with"| node_auth_utils
node_signals -->|"authenticates upgrade"| node_authentication
node_signals -->|"opens socket"| node_websockets
node_websockets -->|"uses"| node_ws_config
node_websockets -->|"enforces"| node_ws_limits
node_websockets -.->|"coordinates when scaled"| node_redis_cache
node_user_sync -->|"dispatches"| node_user_sync_controller
node_user_sync_controller -->|"uses"| node_user_services
node_user_services -->|"persists users"| node_drizzle
node_drizzle -->|"maps"| node_user_schema
node_migration -->|"creates"| node_user_schema
node_cache_service -->|"connects"| node_redis_cache
node_cluster -.->|"orchestrates workers"| node_server
node_container -->|"packages"| node_server
node_compose -->|"runs"| node_container
node_signaling_deployment -->|"runs"| node_container
node_signaling_deployment -->|"uses"| node_redis_deployment
node_redis_deployment -->|"provides Redis"| node_redis_cache
node_ingress -->|"routes traffic"| node_signaling_deployment

click node_server "https://github.com/yuragb/server_for_cam_det/blob/master/src/server.ts"
click node_elysia_index "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/index.ts"
click node_elysia_app "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/app.ts"
click node_routes "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/index.ts"
click node_signals "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/Signals/index.ts"
click node_websockets "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/websockets/index.ts"
click node_ws_config "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/websockets/websocketConfig.ts"
click node_ws_limits "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/websockets/wsLimits.ts"
click node_authentication "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Authentication/index.ts"
click node_auth_utils "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Authentication/utils/index.ts"
click node_cookie_security "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Security/Cooclie/index.ts"
click node_rate_limiter "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Security/RateLimiter/index.ts"
click node_security_headers "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Security/SecurityHeaders/index.ts"
click node_user_sync "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/User/index.ts"
click node_user_sync_controller "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/User/Controllers/sync.controller.ts"
click node_user_services "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/User/Services/index.ts"
click node_redis_cache "https://github.com/yuragb/server_for_cam_det/blob/master/src/Redis/index.ts"
click node_cache_service "https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/infrastructure/cache/cache.service.ts"
click node_drizzle "https://github.com/yuragb/server_for_cam_det/blob/master/src/db/drizzle/index.ts"
click node_user_schema "https://github.com/yuragb/server_for_cam_det/blob/master/src/db/schema/ShalowUsers.ts"
click node_migration "https://github.com/yuragb/server_for_cam_det/blob/master/drizzle/0001_lush_morlocks.sql"
click node_cluster "https://github.com/yuragb/server_for_cam_det/blob/master/src/cluster.ts"
click node_container "https://github.com/yuragb/server_for_cam_det/blob/master/Dockerfile"
click node_compose "https://github.com/yuragb/server_for_cam_det/blob/master/docker-compose.yml"
click node_signaling_deployment "https://github.com/yuragb/server_for_cam_det/blob/master/k3s/05-signaling-app-deployment.yaml"
click node_redis_deployment "https://github.com/yuragb/server_for_cam_det/blob/master/k3s/05-signaling-redis-deployment.yaml"
click node_ingress "https://github.com/yuragb/server_for_cam_det/blob/master/k3s/09-ingress.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_server,node_elysia_index,node_elysia_app,node_routes,node_signals,node_websockets,node_ws_config,node_ws_limits,node_authentication,node_auth_utils,node_cookie_security,node_rate_limiter,node_security_headers,node_user_sync,node_user_sync_controller,node_user_services,node_cluster toneBlue
class node_redis_cache,node_cache_service,node_drizzle,node_user_schema,node_migration toneAmber
class node_container,node_compose,node_signaling_deployment,node_redis_deployment,node_ingress toneMint
```

## Components

### Bun / Elysia service

- [Process startup](https://github.com/yuragb/server_for_cam_det/blob/master/src/server.ts): Bun entrypoint · `src/server.ts`
- [Elysia bootstrap](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/index.ts): app export · `src/Elysia/index.ts`
- [Application composition](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/app.ts): Elysia app · `src/Elysia/app.ts`
- [HTTP routes](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/index.ts): route module · Provides root and health endpoints. · `src/Elysia/modules/Routes/index.ts`
- [Signaling endpoint](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/Signals/index.ts): WebSocket route · Exposes authenticated /ws upgrades. · `src/Elysia/modules/Routes/Signals/index.ts`
- [Peer signaling lifecycle](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/websockets/index.ts): WebSocket service · Registers peers, relays messages, and removes stale connections. · `src/Elysia/modules/websockets/index.ts`
- [Socket configuration](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/websockets/websocketConfig.ts): WebSocket config · `src/Elysia/modules/websockets/websocketConfig.ts`
- [Connection limits](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/websockets/wsLimits.ts): WebSocket limits · `src/Elysia/modules/websockets/wsLimits.ts`
- [JWT authentication](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Authentication/index.ts): auth boundary · Accepts bearer or query-token credentials and validates JWT claims. · `src/Elysia/modules/Authentication/index.ts`
- [JWT validators](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Authentication/utils/index.ts): auth utilities · Uses JWKS or service shared-secret validation. · `src/Elysia/modules/Authentication/utils/index.ts`
- [Cookie security](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Security/Cooclie/index.ts): security module · `src/Elysia/modules/Security/Cooclie/index.ts`
- [Rate limiting](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Security/RateLimiter/index.ts): security middleware · `src/Elysia/modules/Security/RateLimiter/index.ts`
- [Security headers](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Security/SecurityHeaders/index.ts): security middleware · `src/Elysia/modules/Security/SecurityHeaders/index.ts`
- [User synchronization](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/User/index.ts): user API · Separate from realtime signaling. · `src/Elysia/modules/Routes/User/index.ts`
- [Sync controller](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/User/Controllers/sync.controller.ts): controller · `src/Elysia/modules/Routes/User/Controllers/sync.controller.ts`
- [User services](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/Routes/User/Services/index.ts): service layer · `src/Elysia/modules/Routes/User/Services/index.ts`
- [Cluster orchestration](https://github.com/yuragb/server_for_cam_det/blob/master/src/cluster.ts): runtime orchestration · `src/cluster.ts`

### State and persistence

- [Redis cache boundary](https://github.com/yuragb/server_for_cam_det/blob/master/src/Redis/index.ts): cache module · Likely shared coordination boundary for multi-instance peer routing. · `src/Redis/index.ts`
- [Cache service](https://github.com/yuragb/server_for_cam_det/blob/master/src/Elysia/modules/infrastructure/cache/cache.service.ts): cache adapter · `src/Elysia/modules/infrastructure/cache/cache.service.ts`
- [Drizzle persistence](https://github.com/yuragb/server_for_cam_det/blob/master/src/db/drizzle/index.ts): database layer · `src/db/drizzle/index.ts`
- [Shallow users schema](https://github.com/yuragb/server_for_cam_det/blob/master/src/db/schema/ShalowUsers.ts): database schema · `src/db/schema/ShalowUsers.ts`
- [Initial migration](https://github.com/yuragb/server_for_cam_det/blob/master/drizzle/0001_lush_morlocks.sql): SQL migration · `drizzle/0001_lush_morlocks.sql`

### Container and k3s

- [Container image](https://github.com/yuragb/server_for_cam_det/blob/master/Dockerfile): Docker build · `Dockerfile`
- [Local stack](https://github.com/yuragb/server_for_cam_det/blob/master/docker-compose.yml): Docker Compose · `docker-compose.yml`
- [Signaling app workload](https://github.com/yuragb/server_for_cam_det/blob/master/k3s/05-signaling-app-deployment.yaml): k3s deployment · `k3s/05-signaling-app-deployment.yaml`
- [Redis workload](https://github.com/yuragb/server_for_cam_det/blob/master/k3s/05-signaling-redis-deployment.yaml): k3s deployment · `k3s/05-signaling-redis-deployment.yaml`
- [Ingress](https://github.com/yuragb/server_for_cam_det/blob/master/k3s/09-ingress.yaml): k3s ingress · Publishes HTTP, health, and WebSocket traffic. · `k3s/09-ingress.yaml`

## Connections

- Process startup → Elysia bootstrap: starts
- Elysia bootstrap → Application composition: exports
- Application composition → HTTP routes: mounts
- Application composition → JWT authentication: applies
- Application composition → Rate limiting: applies
- Application composition → Security headers: applies
- Application composition → Cookie security: applies
- HTTP routes → Signaling endpoint: routes /ws
- HTTP routes → User synchronization: routes user sync
- JWT authentication → JWT validators: validates with
- Signaling endpoint → JWT authentication: authenticates upgrade
- Signaling endpoint → Peer signaling lifecycle: opens socket
- Peer signaling lifecycle → Socket configuration: uses
- Peer signaling lifecycle → Connection limits: enforces
- Peer signaling lifecycle → Redis cache boundary: coordinates when scaled
- User synchronization → Sync controller: dispatches
- Sync controller → User services: uses
- User services → Drizzle persistence: persists users
- Drizzle persistence → Shallow users schema: maps
- Initial migration → Shallow users schema: creates
- Cache service → Redis cache boundary: connects
- Cluster orchestration → Process startup: orchestrates workers
- Container image → Process startup: packages
- Local stack → Container image: runs
- Signaling app workload → Container image: runs
- Signaling app workload → Redis workload: uses
- Redis workload → Redis cache boundary: provides Redis
- Ingress → Signaling app workload: routes traffic