Architecture Overview

CrowdVision is a distributed, event-driven microservices system. The frontend is fully separated from the backend, and the backend services are isolated from one another, so the platform can scale parts independently, tolerate partial failure, and enforce strict data boundaries.

This page gives the whole-system picture — the components and the two deployment models. Inter-service communication and the real-time data path are covered in Communication & Data Flow; the cluster specifics in Deployment & Kubernetes; the Istio mesh migration in Service Mesh Architecture.

Component Landscape

Libraries

Shared code embedded directly into other services — not independently deployed, no Dockerfile of their own.

Services

Independently deployable, each with its own container image.

The agent runs as part of the system but sits outside this guide’s microservice set; it appears here for completeness only.

Module View

Build-time dependency graph — what needs what to compile. Not the same as request-time calls between services, see Communication & Data Flow.

• crowdvision root splits into frontend and backend — the two top-level trees in the monorepo (frontend/, backend/*).
• auth-contracts — Shared Kernel, dependency floor for every backend module.
• auth-middleware, auth-policy depend on it, nothing else.
• claims-gateway, tenancy pull in the Go auth libs. digital-twin, agent embed only auth-policy’s Cedar bundle (include_str! / cedarpy, not a package import).
• registry, provisioner, telemetry, dashboard, notification, socket, chat — no shared-lib dependency, hang directly off backend.

Deployment Model: Docker Compose (Local Development)

All incoming external traffic enters the system through a single Caddy reverse-proxy gateway exposed on port 80. Caddy strips the service prefixes from the URLs and proxies the requests to the appropriate target containers on the internal Docker bridge network. For protected routes, Caddy’s forward_auth calls claims-gateway’s /verify and copies the resulting X-Gateway-Claims header onto the request — the docker-compose equivalent of Istio’s RequestAuthentication + outputPayloadToHeader in the Kubernetes model below.

Network Segregation & Database Isolation

Each stateful microservice is attached to two networks:

• The shared gateway-net (so Caddy can reach them).
• A private database network (e.g., tenancy-net, twin-net, notification-net, telemetry-net, chat-net, contracts-net, agent-net, registry-net). claims-gateway and provisioner have no private network of their own — both are stateless and own no database.

This is the intended database-per-service boundary: no service is meant to reach another service’s database directly, only through an API call or an event.

Deployment Model: Kubernetes (Production / Staging)

In Kubernetes mode, Caddy is replaced by an Istio Gateway (Gateway API, gatewayClassName: istio) fronting an Istio ambient mesh: a per-node ztunnel DaemonSet gives every pod L4 mTLS and workload identity with no sidecar and no pod restarts, PeerAuthentication enforces STRICT mTLS across the crowdvision namespace, and a RequestAuthentication on the gateway verifies the claims-gateway-issued JWT exactly once — the validated payload is injected as a single x-gateway-claims header via outputPayloadToHeader, and every downstream service decodes that header instead of re-verifying the JWT itself. The full phased migration is documented in Service Mesh Architecture.

A key difference in the Kubernetes model is how the Sensor Simulator integrates. Because the simulator is an external Docker container (not a cluster workload), it reaches the cluster through the load balancer’s public port, just like a browser. See the External Sensor Simulator page. The cluster internals — StatefulSets, Secrets, Gateway API routes — are detailed in Deployment & Kubernetes; the mesh internals (ztunnel, RequestAuthentication, AuthorizationPolicy, Cedar) in Service Mesh Architecture.

agent is deliberately excluded from the mesh’s AuthorizationPolicy-enforced JWT gate: it also serves a local-dev evaluation bypass token that never holds a real gateway JWT, so it keeps checking for the mesh claims header first and falls back to its own token verification in-process.

Routing Table

The routing table is identical across both deployment models. Only the component enforcing it differs (Caddy vs Istio Gateway API).