Skip to main content

Deployment Topology

:::info Source Sourced from services/analytics-service/DEPLOYMENT_TOPOLOGY.md in the documentation repo. :::

1. Containers​

  • analytics-api — REST API.
  • analytics-firehose — NATS → Kafka → ClickHouse ingest.
  • analytics-export-worker — long-running export jobs.
  • analytics-report-scheduler — cron-driven reports.
  • analytics-cohort-evaluator — hourly cohort materialization.
  • analytics-anomaly-detector — scheduled anomaly scans (M5+).
  • analytics-ai-worker — AI insight generation (M5+).

2. ClickHouse Cluster​

  • 3-node minimum per region; replicated + sharded.
  • Cold tier: S3-backed storage (Parquet) via ClickHouse TTL.
  • Audit-tier: separate cluster, restricted IAM.

3. Scaling​

ContainerMinMaxHPA
api320CPU>60%
firehose315consumer lag > 5s
export-worker215queue > 20
ai-worker210queue > 20

4. Resources​

api: 500m/2000m, 512Mi/2Gi. firehose: 500m/2000m, 512Mi/2Gi. export-worker: 1000m/4000m, 2Gi/8Gi.

5. Caching​

  • Redis: dashboard widget cache (60s), metric query cache (configurable per metric).

6. Regional​

  • Per region. Events pinned to tenant homeRegion for residency.
  • Cross-region analytics for platform-admin via secure tunnel.

7. Service Mesh​

mTLS. Egress: ai-gateway, notification (for alerts), S3 (exports).

8. Release​

Blue/green API. Rolling firehose (resumes from Kafka offset). Schema migrations coordinated with producers.

9. DR​

  • RPO 5 min (Kafka retention).
  • Can rebuild ClickHouse tables from Kafka + event log.
  • Cold archive durable on S3 with cross-region replication.

10. Diagram​

All services → NATS → (Kafka Connect bridge) → Kafka → ClickHouse raw
                                                             │
                                                             ▼
                                                    Materialized Views
                                                             │
                                                             ├─ analytics-api (dashboards, queries)
                                                             ├─ export-worker (async exports)
                                                             ├─ cohort-evaluator
                                                             ├─ anomaly-detector
                                                             └─ ai-worker (insights)