# githubtron/venueflow architecture

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

- Interactive diagram: https://gitdiagram.com/githubtron/venueflow
- Repository: https://github.com/githubtron/venueflow

## Overview

1. **This is a TypeScript/Python monorepo for a real-time venue operations platform.**  
   The repository is split into frontend apps, many small backend services, shared type definitions, and local infrastructure. Most backend services are independently deployable and each owns a narrow domain: auth, entry, notifications, wayfinding, analytics, emergency, staff, vendors, rewards, compliance, incidents, and ML/simulation.

2. **The core event-data pipeline starts at the edge and fans out through Kafka.**  
   The main operational flow is: IoT sensors send telemetry over MQTT into `services/iot-gateway`, which validates/normalizes payloads and publishes to Kafka. From there, downstream consumers like `heatmap-engine`, `entry-router`, `rewards-service`, and other event-driven services react to the same stream.

3. **Heat and crowd intelligence is a dedicated real-time subsystem.**  
   `services/heatmap-engine` is a Python FastAPI service with a Kafka consumer, an in-memory/Redis-backed store, aggregation/classification logic, and HTTP routes for reading computed heatmap state. The README’s architecture shows its output feeds Redis and then a WebSocket gateway, which is how live crowd state reaches clients.

4. **Entry management is a separate transactional boundary.**  
   `services/entry-router` handles ticket validation/scoring and writes entry events to PostgreSQL. It also has a Redis client and a red-zone subscriber, so it combines stateful checks with near-real-time gating decisions rather than relying only on the central telemetry stream.

5. **Authentication and authorization are isolated in their own service.**  
   `services/auth-service` owns login, JWT/keys, and RBAC middleware with a PostgreSQL migration. Frontends use auth-specific hooks/providers and guard components, so access control is enforced both in UI and at the API boundary.

6. **Attendee and staff experiences are split into two client applications.**  
   `apps/mobile` is a React Native app scaffold with screens for ticketing, navigation, kiosks, rewards, incident reporting, evacuation, and SOS. `apps/dashboard` is a React/Vite ops console with live maps, staff management, vendor views, compliance, emergency, and analytics pages. Both apps include WebSocket hooks for live updates.

7. **Notifications are delivered through multiple channels behind one service.**  
   `services/notification-service` centralizes delivery logic for WebSocket push, BLE mesh, staff radio, and segmented channels. That makes it the broadcast layer for alerts such as anomalies, emergencies, and targeted operational messages rather than embedding delivery logic in each domain service.

8. **Operational domains are modeled as small services with their own storage.**  
   There are dedicated services for staff management, vendor intelligence, kiosk orders, rewards, compliance, incidents, emergency coordination, and wayfinding. Most of these use PostgreSQL migrations and expose a narrow HTTP API; a few also consume Kafka or publish events. This keeps each business area independently evolvable.

9. **Analytics and ML are isolated from the live control plane.**  
   `services/analytics-service`, `queue-predictor`, `sponsor-analytics`, `ml-pipeline`, and `simulation-service` are separate Python FastAPI services for reporting, prediction, training, and synthetic event generation. `services/threat-detection` and `services/external-integration` extend the platform with risk detection and external feeds like traffic/weather. These services inform the product but are not in the critical ingress/egress path.

10. **Shared contracts and infra are first-class parts of the architecture.**  
   `packages/shared-types` holds cross-service TypeScript types, reducing drift across frontend and backend boundaries. `infra/docker-compose.yml` provides local Kafka/Postgres/Redis-style infrastructure, while `infra/cdk` contains planned cloud deployment stacks. The repo is therefore structured for local composition now, with a clear migration path to AWS-style managed infrastructure.

11. **State is intentionally decentralized by domain.**  
   PostgreSQL is used for transactional service-owned data, Redis for low-latency live state, Kafka for event distribution, and WebSockets for client push. The architecture avoids a single central application server; instead, it connects specialized services through well-defined data flows and shared event contracts.

12. **Testing mirrors the service boundaries.**  
   Most services include unit/property tests near the logic they own, and the Python services add Hypothesis-based property tests. That’s a signal that correctness is expected to be enforced per subsystem rather than through a single end-to-end test layer.

Main entry points: [`infra/docker-compose.yml`](https://github.com/githubtron/venueflow/blob/main/infra/docker-compose.yml) (Compose infra), [`apps/dashboard`](https://github.com/githubtron/venueflow/tree/main/apps/dashboard) (Dashboard), [`infra/kafka/init-topics.sh`](https://github.com/githubtron/venueflow/blob/main/infra/kafka/init-topics.sh) (Kafka bus), [`services/notification-service`](https://github.com/githubtron/venueflow/tree/main/services/notification-service) (Notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Client apps"]
  node_app_dashboard["Dashboard<br/>react ops console"]
  node_app_mobile["Mobile app<br/>react native client"]
end

subgraph group_services["Platform services"]
  node_auth_service["Auth service<br/>jwt/rbac service"]
  node_event_service["Event service<br/>event registry"]
  node_iot_gateway["IoT gateway<br/>mqtt->kafka edge"]
  node_heatmap_engine["Heatmap engine<br/>realtime crowd processor"]
  node_entry_router["Entry router<br/>ticket gate service"]
  node_notification_service["Notifications<br/>broadcast service"]
  node_rewards_service["Rewards<br/>event consumer"]
  node_staff_service["Staff management<br/>staff domain api"]
  node_vendor_service["Vendor intelligence<br/>vendor domain api"]
  node_compliance_service["Compliance<br/>capacity checks"]
  node_incident_service["Incidents<br/>incident prioritizer"]
  node_emergency_service["Emergency<br/>coordination service"]
  node_kiosk_service["Kiosk orders<br/>order service"]
  node_wayfinding_engine["Wayfinding<br/>routing engine"]
  node_external_integration["External feeds<br/>traffic/weather adapter"]
end

subgraph group_ml["Analytics and ML"]
  node_analytics_service["Analytics<br/>reporting service"]
  node_queue_predictor["Queue predictor<br/>prediction service"]
  node_threat_detection["Threat detection<br/>risk detector"]
  node_ml_pipeline["ML pipeline<br/>training service"]
  node_simulation_service["Simulation<br/>synthetic event service"]
end

subgraph group_shared["Shared and infra"]
  node_kafka_bus[("Kafka bus<br/>event backbone<br/>[init-topics.sh]")]
  node_shared_types["Shared types<br/>ts contracts"]
  node_docker_compose[("Compose infra<br/>local infra<br/>[docker-compose.yml]")]
  node_cdk_stacks["CDK stacks<br/>cloud deployment<br/>[ecs-autoscaling.ts]"]
end

node_app_dashboard -->|"login/guards"| node_auth_service
node_app_mobile -->|"login/guards"| node_auth_service
node_app_dashboard -->|"live updates"| node_notification_service
node_app_mobile -->|"push/live"| node_notification_service
node_app_dashboard -->|"heatmap reads"| node_heatmap_engine
node_app_mobile -->|"navigation"| node_wayfinding_engine
node_app_mobile -->|"orders"| node_kiosk_service
node_app_dashboard -->|"staff ops"| node_staff_service
node_app_dashboard -->|"vendor ops"| node_vendor_service
node_app_dashboard -->|"compliance"| node_compliance_service
node_iot_gateway -->|"publish"| node_kafka_bus
node_kafka_bus -->|"consume"| node_heatmap_engine
node_kafka_bus -->|"consume"| node_rewards_service
node_entry_router -->|"contracts"| node_shared_types
node_entry_router -.->|"local deps"| node_docker_compose
node_heatmap_engine -->|"state push"| node_notification_service
node_entry_router -->|"alerts"| node_notification_service
node_emergency_service -->|"broadcast"| node_notification_service
node_external_integration -->|"feeds"| node_threat_detection
node_analytics_service -->|"contracts"| node_shared_types
node_queue_predictor -.->|"signals"| node_kafka_bus
node_simulation_service -.->|"synthetic events"| node_kafka_bus
node_auth_service -.->|"postgres"| node_docker_compose
node_staff_service -.->|"postgres"| node_docker_compose
node_vendor_service -.->|"postgres"| node_docker_compose
node_compliance_service -.->|"postgres"| node_docker_compose
node_incident_service -.->|"postgres"| node_docker_compose
node_kiosk_service -.->|"postgres"| node_docker_compose
node_cdk_stacks -.->|"migration path"| node_docker_compose

click node_app_dashboard "https://github.com/githubtron/venueflow/tree/main/apps/dashboard"
click node_app_mobile "https://github.com/githubtron/venueflow/tree/main/apps/mobile"
click node_auth_service "https://github.com/githubtron/venueflow/tree/main/services/auth-service"
click node_event_service "https://github.com/githubtron/venueflow/tree/main/services/event-service"
click node_iot_gateway "https://github.com/githubtron/venueflow/tree/main/services/iot-gateway"
click node_kafka_bus "https://github.com/githubtron/venueflow/blob/main/infra/kafka/init-topics.sh"
click node_heatmap_engine "https://github.com/githubtron/venueflow/tree/main/services/heatmap-engine"
click node_entry_router "https://github.com/githubtron/venueflow/tree/main/services/entry-router"
click node_notification_service "https://github.com/githubtron/venueflow/tree/main/services/notification-service"
click node_rewards_service "https://github.com/githubtron/venueflow/tree/main/services/rewards-service"
click node_staff_service "https://github.com/githubtron/venueflow/tree/main/services/staff-management"
click node_vendor_service "https://github.com/githubtron/venueflow/tree/main/services/vendor-intelligence"
click node_compliance_service "https://github.com/githubtron/venueflow/tree/main/services/compliance-service"
click node_incident_service "https://github.com/githubtron/venueflow/tree/main/services/incident-service"
click node_emergency_service "https://github.com/githubtron/venueflow/tree/main/services/emergency-coordinator"
click node_kiosk_service "https://github.com/githubtron/venueflow/tree/main/services/kiosk-service"
click node_wayfinding_engine "https://github.com/githubtron/venueflow/tree/main/services/wayfinding-engine"
click node_external_integration "https://github.com/githubtron/venueflow/tree/main/services/external-integration"
click node_analytics_service "https://github.com/githubtron/venueflow/tree/main/services/analytics-service"
click node_queue_predictor "https://github.com/githubtron/venueflow/tree/main/services/queue-predictor"
click node_threat_detection "https://github.com/githubtron/venueflow/tree/main/services/threat-detection"
click node_ml_pipeline "https://github.com/githubtron/venueflow/tree/main/services/ml-pipeline"
click node_simulation_service "https://github.com/githubtron/venueflow/tree/main/services/simulation-service"
click node_shared_types "https://github.com/githubtron/venueflow/tree/main/packages/shared-types"
click node_docker_compose "https://github.com/githubtron/venueflow/blob/main/infra/docker-compose.yml"
click node_cdk_stacks "https://github.com/githubtron/venueflow/blob/main/infra/cdk/stacks/ecs-autoscaling.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_app_dashboard,node_app_mobile toneBlue
class node_auth_service,node_event_service,node_iot_gateway,node_heatmap_engine,node_entry_router,node_notification_service,node_rewards_service,node_staff_service,node_vendor_service,node_compliance_service,node_incident_service,node_emergency_service,node_kiosk_service,node_wayfinding_engine,node_external_integration toneAmber
class node_analytics_service,node_queue_predictor,node_threat_detection,node_ml_pipeline,node_simulation_service toneMint
class node_kafka_bus,node_shared_types,node_docker_compose,node_cdk_stacks toneRose
```

## Components

### Client apps

End-user and operator interfaces

- [Dashboard](https://github.com/githubtron/venueflow/tree/main/apps/dashboard): react ops console · Operations web console for maps, staff, vendors, compliance, emergencies, and analytics · `apps/dashboard`
- [Mobile app](https://github.com/githubtron/venueflow/tree/main/apps/mobile): react native client · Attendee and staff mobile app for tickets, navigation, rewards, incidents, and SOS · `apps/mobile`

### Platform services

Domain services and event processors

- [Auth service](https://github.com/githubtron/venueflow/tree/main/services/auth-service): jwt/rbac service · Login, keys, JWT, and authorization middleware backed by PostgreSQL · `services/auth-service`
- [Event service](https://github.com/githubtron/venueflow/tree/main/services/event-service): event registry · Event and venue event API with its own PostgreSQL schema · `services/event-service`
- [IoT gateway](https://github.com/githubtron/venueflow/tree/main/services/iot-gateway): mqtt->kafka edge · Validates sensor telemetry and publishes normalized events to Kafka · `services/iot-gateway`
- [Heatmap engine](https://github.com/githubtron/venueflow/tree/main/services/heatmap-engine): realtime crowd processor · Consumes telemetry, aggregates heat state, stores live state, and serves heatmap reads · `services/heatmap-engine`
- [Entry router](https://github.com/githubtron/venueflow/tree/main/services/entry-router): ticket gate service · Ticket validation and scoring with PostgreSQL entry events and Redis-backed gating state · `services/entry-router`
- [Notifications](https://github.com/githubtron/venueflow/tree/main/services/notification-service): broadcast service · Multi-channel alert delivery over WebSocket, BLE mesh, staff radio, and segmented channels · `services/notification-service`
- [Rewards](https://github.com/githubtron/venueflow/tree/main/services/rewards-service): event consumer · Rewards processing driven by Kafka event consumption · `services/rewards-service`
- [Staff management](https://github.com/githubtron/venueflow/tree/main/services/staff-management): staff domain api · Staff shifts, redeployment, incidents, and location operations with PostgreSQL storage · `services/staff-management`
- [Vendor intelligence](https://github.com/githubtron/venueflow/tree/main/services/vendor-intelligence): vendor domain api · Vendor analytics, pricing, inventory, and SLA management with PostgreSQL storage · `services/vendor-intelligence`
- [Compliance](https://github.com/githubtron/venueflow/tree/main/services/compliance-service): capacity checks · Capacity and compliance checks with its own schema · `services/compliance-service`
- [Incidents](https://github.com/githubtron/venueflow/tree/main/services/incident-service): incident prioritizer · Incident prioritization and incident data storage · `services/incident-service`
- [Emergency](https://github.com/githubtron/venueflow/tree/main/services/emergency-coordinator): coordination service · Emergency and medical coordination plus Kafka event publication · `services/emergency-coordinator`
- [Kiosk orders](https://github.com/githubtron/venueflow/tree/main/services/kiosk-service): order service · Kiosk ordering API backed by PostgreSQL · `services/kiosk-service`
- [Wayfinding](https://github.com/githubtron/venueflow/tree/main/services/wayfinding-engine): routing engine · Pathfinding and navigation API over venue graphs · `services/wayfinding-engine`
- [External feeds](https://github.com/githubtron/venueflow/tree/main/services/external-integration): traffic/weather adapter · Adapts traffic and weather inputs into the platform · `services/external-integration`

### Analytics and ML

Reporting, prediction, simulation, and risk analysis

- [Analytics](https://github.com/githubtron/venueflow/tree/main/services/analytics-service): reporting service · Operational analytics, replay, and trend reporting · `services/analytics-service`
- [Queue predictor](https://github.com/githubtron/venueflow/tree/main/services/queue-predictor): prediction service · Predicts queue behavior and schedules forecast runs · `services/queue-predictor`
- [Threat detection](https://github.com/githubtron/venueflow/tree/main/services/threat-detection): risk detector · Detects threats from platform and external signals · `services/threat-detection`
- [ML pipeline](https://github.com/githubtron/venueflow/tree/main/services/ml-pipeline): training service · Model training and pipeline orchestration · `services/ml-pipeline`
- [Simulation](https://github.com/githubtron/venueflow/tree/main/services/simulation-service): synthetic event service · Generates simulated venue events for testing and planning · `services/simulation-service`

### Shared and infra

Cross-cutting contracts and local infrastructure

- [Kafka bus](https://github.com/githubtron/venueflow/blob/main/infra/kafka/init-topics.sh): event backbone · Shared event distribution layer for telemetry and downstream consumers · `infra/kafka/init-topics.sh`
- [Shared types](https://github.com/githubtron/venueflow/tree/main/packages/shared-types): ts contracts · Cross-service TypeScript event and domain contracts · `packages/shared-types`
- [Compose infra](https://github.com/githubtron/venueflow/blob/main/infra/docker-compose.yml): local infra · Local Kafka, PostgreSQL, and Redis-style development environment · `infra/docker-compose.yml`
- [CDK stacks](https://github.com/githubtron/venueflow/blob/main/infra/cdk/stacks/ecs-autoscaling.ts): cloud deployment · Planned AWS deployment and failover infrastructure · `infra/cdk/stacks/ecs-autoscaling.ts`

## Connections

- Dashboard → Auth service: login/guards · Dashboard authenticates and authorizes via the auth service
- Mobile app → Auth service: login/guards · Mobile app uses auth for identity and access control
- Dashboard → Notifications: live updates · Dashboard receives pushed operational alerts and state changes
- Mobile app → Notifications: push/live · Mobile app receives live operational messages and alerts
- Dashboard → Heatmap engine: heatmap reads · Dashboard reads live crowd state for map visualizations
- Mobile app → Wayfinding: navigation · Mobile app requests navigation and routing guidance
- Mobile app → Kiosk orders: orders · Mobile app places and tracks kiosk orders
- Dashboard → Staff management: staff ops · Dashboard manages staff operations and redeployments
- Dashboard → Vendor intelligence: vendor ops · Dashboard views vendor intelligence and operations
- Dashboard → Compliance: compliance · Dashboard uses compliance and capacity views
- IoT gateway → Kafka bus: publish · Normalized telemetry is published to Kafka
- Kafka bus → Heatmap engine: consume · Heatmap engine consumes telemetry events from Kafka
- Kafka bus → Rewards: consume · Rewards service reacts to shared event streams
- Entry router → Shared types: contracts · Entry routing uses shared domain contracts
- Entry router → Compose infra: local deps · Entry routing depends on local database and cache infrastructure
- Heatmap engine → Notifications: state push · Computed crowd state can be forwarded to client push channels
- Entry router → Notifications: alerts · Entry decisions can trigger operational notifications
- Emergency → Notifications: broadcast · Emergency coordination uses the notification broadcast layer
- External feeds → Threat detection: feeds · External traffic and weather signals inform threat detection
- Analytics → Shared types: contracts · Analytics shares domain contracts with other services
- Queue predictor → Kafka bus: signals · Prediction inputs and outputs align with the event backbone
- Simulation → Kafka bus: synthetic events · Simulation can generate event traffic for downstream consumers
- Auth service → Compose infra: postgres · Auth service uses local database infrastructure
- Staff management → Compose infra: postgres · Staff service uses local database infrastructure
- Vendor intelligence → Compose infra: postgres · Vendor service uses local database infrastructure
- Compliance → Compose infra: postgres · Compliance service uses local database infrastructure
- Incidents → Compose infra: postgres · Incident service uses local database infrastructure
- Kiosk orders → Compose infra: postgres · Kiosk service uses local database infrastructure
- CDK stacks → Compose infra: migration path · CDK stacks represent the cloud deployment evolution of local infrastructure