# soumyodipto68/live-location-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/soumyodipto68/live-location-tracker
- Repository: https://github.com/soumyodipto68/live-location-tracker

## Overview

Live Location Tracker authenticates users with OIDC, accepts validated location updates over Socket.IO, and publishes them to Kafka. Kafka is the source of truth: one consumer deduplicates and rejects stale events before updating Redis and publishing broadcasts; the server relays those broadcasts to connected clients. A separate consumer handles location persistence/logging. The README documents the UI/map and consumer roles; unsampled UI behavior and deployment details are not inferred beyond that.

Main entry points: [`src/index.ts`](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/index.ts) (HTTP and Socket server), [`src/lib/location-consumer.ts`](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/location-consumer.ts) (Broadcast consumer), [`src/lib/redis.ts`](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/redis.ts) (Redis clients), [`src/lib/socket-handlers.ts`](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/socket-handlers.ts) (Socket handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth["Authentication"]
  node_auth_routes["Auth routes<br/>[auth.ts]"]
  node_oidc["OIDC service<br/>[oidc.ts]"]
  node_session["Session middleware<br/>[session.ts]"]
  node_config["Configuration<br/>[config.ts]"]
end

subgraph group_realtime["Realtime location"]
  node_server["HTTP and Socket server<br/>[index.ts]"]
  node_socket["Socket handlers<br/>[socket-handlers.ts]"]
  node_validation["Location validation"]
end

subgraph group_state["State and processing"]
  node_kafka_client["Kafka client<br/>[kafka-client.ts]"]
  node_location_consumer["Broadcast consumer"]
  node_db_processor["History processor"]
  node_cleanup["Stale-user cleanup"]
  node_redis["Redis clients<br/>[redis.ts]"]
end

subgraph group_client["Client experience"]
  node_browser["Map client<br/>[script.js]"]
end

node_user(("User"))
node_identity_provider["OIDC provider"]
node_kafka["Kafka"]
node_redis_service[("Redis")]
node_database[("Location database")]

node_user -->|"uses map"| node_browser
node_browser -->|"sends updates"| node_server
node_server -->|"mounts routes"| node_auth_routes
node_server -->|"installs middleware"| node_session
node_auth_routes -->|"requests OIDC"| node_oidc
node_oidc -->|"reads settings"| node_config
node_oidc -->|"discovers and exchanges"| node_identity_provider
node_server -->|"attaches handlers"| node_socket
node_socket -->|"validates payload"| node_validation
node_socket -.->|"publishes updates"| node_kafka_client
node_socket -->|"reads and clears metadata"| node_redis
node_server -->|"creates consumers"| node_kafka_client
node_server -->|"starts consumer"| node_location_consumer
node_location_consumer -->|"checks events"| node_validation
node_location_consumer -->|"deduplicates and updates"| node_redis
node_location_consumer -->|"consumes updates"| node_kafka
node_location_consumer -->|"stores state"| node_redis_service
node_location_consumer -->|"publishes broadcasts"| node_redis
node_server -->|"subscribes to broadcasts"| node_redis
node_server -->|"relays location events"| node_browser
node_server -->|"starts cleanup"| node_cleanup
node_cleanup -->|"removes stale users"| node_redis
node_cleanup -.->|"signals disconnect"| node_server
node_db_processor -->|"creates consumer"| node_kafka_client
node_db_processor -->|"consumes updates"| node_kafka
node_db_processor -.->|"persists location history"| node_database

click node_browser "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/public/script.js"
click node_server "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/index.ts"
click node_socket "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/socket-handlers.ts"
click node_validation "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/location-validation.ts"
click node_kafka_client "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/kafka-client.ts"
click node_location_consumer "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/location-consumer.ts"
click node_db_processor "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/database-processor.ts"
click node_cleanup "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/stale-user-cleanup.ts"
click node_redis "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/redis.ts"
click node_auth_routes "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/routes/auth.ts"
click node_oidc "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/services/oidc.ts"
click node_session "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/session.ts"
click node_config "https://github.com/soumyodipto68/live-location-tracker/blob/main/src/config.ts"

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_auth_routes,node_oidc,node_session,node_config,node_user toneBlue
class node_server,node_socket,node_validation,node_redis_service,node_database toneAmber
class node_kafka_client,node_location_consumer,node_db_processor,node_cleanup,node_redis toneMint
class node_browser toneRose
class node_identity_provider,node_kafka toneIndigo
```

## Components

### Authentication

- [Auth routes](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/routes/auth.ts): `src/routes/auth.ts`
- [OIDC service](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/services/oidc.ts): `src/services/oidc.ts`
- [Session middleware](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/session.ts): `src/lib/session.ts`
- [Configuration](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/config.ts): `src/config.ts`

### Realtime location

- [HTTP and Socket server](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/index.ts): `src/index.ts`
- [Socket handlers](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/socket-handlers.ts): `src/lib/socket-handlers.ts`
- [Location validation](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/location-validation.ts): `src/lib/location-validation.ts`

### State and processing

- [Kafka client](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/kafka-client.ts): `src/lib/kafka-client.ts`
- [Broadcast consumer](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/location-consumer.ts): `src/lib/location-consumer.ts`
- [History processor](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/database-processor.ts): `src/lib/database-processor.ts`
- [Stale-user cleanup](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/stale-user-cleanup.ts): `src/lib/stale-user-cleanup.ts`
- [Redis clients](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/lib/redis.ts): `src/lib/redis.ts`

### Client experience

- [Map client](https://github.com/soumyodipto68/live-location-tracker/blob/main/src/public/script.js): `src/public/script.js`

### Other components

- **User**
- **OIDC provider**
- **Kafka**
- **Redis**
- **Location database**

## Connections

- User → Map client: uses map (evidence: `README.md`)
- Map client → HTTP and Socket server: sends updates (evidence: `README.md`)
- HTTP and Socket server → Auth routes: mounts routes (evidence: `src/index.ts`)
- HTTP and Socket server → Session middleware: installs middleware (evidence: `src/index.ts`)
- Auth routes → OIDC service: requests OIDC (evidence: `src/routes/auth.ts`)
- OIDC service → Configuration: reads settings (evidence: `src/services/oidc.ts`)
- OIDC service → OIDC provider: discovers and exchanges (evidence: `src/services/oidc.ts`)
- HTTP and Socket server → Socket handlers: attaches handlers (evidence: `src/index.ts`)
- Socket handlers → Location validation: validates payload (evidence: `src/lib/socket-handlers.ts`)
- Socket handlers → Kafka client: publishes updates
- Socket handlers → Redis clients: reads and clears metadata (evidence: `src/lib/socket-handlers.ts`)
- HTTP and Socket server → Kafka client: creates consumers (evidence: `src/index.ts`)
- HTTP and Socket server → Broadcast consumer: starts consumer (evidence: `src/index.ts`)
- Broadcast consumer → Location validation: checks events (evidence: `src/lib/location-consumer.ts`)
- Broadcast consumer → Redis clients: deduplicates and updates (evidence: `src/lib/location-consumer.ts`)
- Broadcast consumer → Kafka: consumes updates (evidence: `README.md`)
- Broadcast consumer → Redis: stores state (evidence: `src/lib/location-consumer.ts`)
- Broadcast consumer → Redis clients: publishes broadcasts (evidence: `src/lib/location-consumer.ts`)
- HTTP and Socket server → Redis clients: subscribes to broadcasts (evidence: `src/index.ts`)
- HTTP and Socket server → Map client: relays location events (evidence: `README.md`)
- HTTP and Socket server → Stale-user cleanup: starts cleanup (evidence: `src/index.ts`)
- Stale-user cleanup → Redis clients: removes stale users (evidence: `src/lib/stale-user-cleanup.ts`)
- Stale-user cleanup → HTTP and Socket server: signals disconnect (evidence: `src/index.ts`)
- History processor → Kafka client: creates consumer (evidence: `src/lib/database-processor.ts`)
- History processor → Kafka: consumes updates (evidence: `README.md`)
- History processor → Location database: persists location history
