Skip to main content

Domain Model

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

1. Aggregates​

AnalyticsEvent (projection, not authoritative)​

interface AnalyticsEvent {
  tenantId: TenantId;
  eventName: string;
  properties: Record<string, JSONValue>;
  actor: { type: string; id: string };   // actor.id is hashed
  occurredAt: ISODate;
  ingestedAt: ISODate;
  correlationId: string;
}

MetricDefinition​

interface MetricDefinition {
  id: ULID;
  tenantId: TenantId | null;                // null = platform metric
  name: string;
  description: I18nString;
  query: string;                             // SQL template over ClickHouse
  schedule?: string;                         // cron, if materialized
  unit: 'count' | 'ratio' | 'seconds' | 'bytes' | 'microUSD';
  status: 'active' | 'deprecated';
}

Dashboard​

interface Dashboard {
  id: ULID;
  tenantId: TenantId;
  name: string;
  widgets: Widget[];
  accessControl: { allowedRoles: string[]; allowedUsers: UserId[] };
  createdBy: UserId;
}
interface Widget { id: ULID; type: 'line'|'bar'|'pie'|'table'|'bignumber'|'map'|'text'; metricId: ULID; dimensions: string[]; filters?: Record<string, JSONValue>; }

Report​

interface Report {
  id: ULID;
  tenantId: TenantId;
  name: string;
  query: string;
  schedule?: string;        // daily, weekly, monthly
  format: 'csv' | 'xlsx' | 'pdf';
  recipients: Email[];
}

ExportJob​

interface ExportJob {
  id: ULID;
  tenantId: TenantId;
  requestedBy: UserId;
  query: string;
  format: 'csv' | 'xlsx' | 'json';
  filters: Record<string, JSONValue>;
  status: 'queued' | 'running' | 'completed' | 'failed';
  outputUrl?: string;
  createdAt: ISODate;
  completedAt?: ISODate;
}

CohortDefinition​

interface CohortDefinition {
  id: ULID;
  tenantId: TenantId;
  name: string;
  criteria: CohortCriteria;    // e.g., "users enrolled in course X in Q1"
}

2. Invariants​

  • Events append-only; no mutation.
  • Tenant-scoped queries; cross-tenant aggregations for platform metrics only (admin-scoped).
  • PII-free event payloads in hot tier; restricted-access audit tier has full PII.

3. Events Published​

  • analytics.export.completed.v1, .failed.v1
  • analytics.alert.triggered.v1 (e.g., anomaly detected)
  • analytics.cohort.evaluated.v1
  • analytics.report.rendered.v1

4. Events Consumed​

  • Every domain event from every service (firehose).
  • Processes for: raw event storage, materialized views, cohort evaluation, anomaly detection.

5. Diagram​

All services' NATS ──▶ Firehose (NATS + Kafka Connect) ──▶ ClickHouse raw
                                                               │
                                                               ▼
                                                       Materialized views
                                                               │
                                                               ├─▶ Dashboards
                                                               ├─▶ Reports
                                                               ├─▶ Exports
                                                               └─▶ AI insights