Application Logic

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

1. Application Services

• FirehoseIngestor — NATS → Kafka → ClickHouse.
• MetricRegistryService — manage metric definitions.
• DashboardService — CRUD + query + render.
• ReportSchedulerService — scheduled reports.
• ExportService — large exports (async).
• CohortService — cohort definition + evaluation.
• AIInsightsService (M5+) — NL queries, anomaly detection, forecasts.

2. Commands

Command	Trigger
IngestEvent	NATS firehose
CreateMetric / UpdateMetric / DeprecateMetric	Admin
CreateDashboard / UpdateDashboard`	Tenant admin
ExportQuery	Tenant admin
ScheduleReport	Tenant admin
EvaluateCohort	Scheduled or on-demand

3. Queries

• dashboard.render(id, filters) — returns widget data.
• metric.query(id, dimensions, filters, timeRange).
• events.query(sql, tenantId) — ad-hoc (restricted).
• export.status(id).

4. Sagas / Policies

• GDPR Erasure participation: delete hot-tier PII rows for user; anonymize cold-tier.
• Retention policy: 13 months hot in ClickHouse; 5 years cold in S3 Parquet.

5. Use Case Flows

5.1 Learner Dashboard

Tenant admin requests /dashboards/learner-progress:
 │
 ▼
Load Dashboard by ID.
For each widget: resolve metric; query ClickHouse (tenant-scoped).
Return widget data (cached 60s per widget per filter).

5.2 Export Job

Admin POSTs /exports with query + format.
 │
 ▼
Create ExportJob (queued).
Worker picks up; runs query against ClickHouse (scoped to tenant).
Writes CSV/XLSX/JSON to S3 (tenant prefix).
Signed URL returned.
Emits export.completed.v1.

5.3 Cohort Evaluation

Cron hourly:
 For each active cohort:
   Evaluate criteria against ClickHouse.
   Materialize cohort_users table entry.
   Emit cohort.evaluated.v1 (downstream: notification, assignment).

5.4 AI Insight (M5+)

Admin: "Why is retention dropping in June?"
 │
 ▼
AIInsightService → ai-gateway:
  - System prompt: schema awareness + metric catalog.
  - Tool use: execute SQL against ClickHouse.
  - Generate explanation + charts.
 │
 ▼
Return with AIProvenance + confidence.
HITL: admin marks useful/not-useful; feeds prompt eval.

5.5 Anomaly Detection (M5+)

Scheduled: for each key metric:
  Run ARIMA / Prophet / LLM-based detector.
  If anomaly confidence > threshold: emit analytics.alert.triggered.v1.
  Notification routed to tenant admin.