git.stella-ops.org/docs/modules/timeline/architecture.md

# Timeline Architecture

> Query and presentation service for HLC-ordered cross-service event timelines.

## Overview

Timeline provides a REST API for querying, analyzing, and replaying events that have been indexed by the TimelineIndexer module. All events carry Hybrid Logical Clock (HLC) timestamps that establish causal ordering across distributed services. The service supports correlation-based queries, critical path analysis for latency diagnosis, service-scoped views, and deterministic event replay.

## Components

```
src/Timeline/
  StellaOps.Timeline.WebService/              # Timeline REST API (ASP.NET Core)
    Audit/                                    # Unified audit contracts, provider, and aggregation service
    Endpoints/
      TimelineEndpoints.cs                    # Core timeline query endpoints
      ExportEndpoints.cs                      # Event export endpoints
      ReplayEndpoints.cs                      # Deterministic replay endpoints
      UnifiedAuditEndpoints.cs                # Unified /api/v1/audit aggregation endpoints
    Program.cs                                # Host configuration
  StellaOps.TimelineIndexer.WebService/       # Indexer REST API (ASP.NET Core)
    Program.cs                                # Host configuration
    TimelineAuthorizationAuditSink.cs         # Authorization audit sink
  StellaOps.TimelineIndexer.Worker/           # Background ingestion worker (separately deployable)
    TimelineIngestionWorker.cs                # Background event ingestion
    Program.cs                                # Worker host configuration
  __Libraries/
    StellaOps.Timeline.Core/                  # Query service and models
      ITimelineQueryService.cs                # Core query interface
      TimelineQueryService.cs                 # Query implementation
    StellaOps.TimelineIndexer.Core/           # Ingestion domain logic
      Abstractions/                           # ITimelineEventStore, ITimelineIngestionService, etc.
      Models/                                 # TimelineEventEnvelope, TimelineEventView, etc.
      Services/                               # TimelineIngestionService, TimelineQueryService
    StellaOps.TimelineIndexer.Infrastructure/ # Persistence, EfCore, messaging subscribers
      Db/                                     # Migrations, event store, query store
      EfCore/                                 # Compiled models, context, entity models
      Subscriptions/                          # NATS, Redis, Null subscribers
  __Tests/
    StellaOps.Timeline.Core.Tests/            # Timeline query tests
    StellaOps.Timeline.WebService.Tests/      # Timeline API integration tests
    StellaOps.TimelineIndexer.Tests/          # Indexer unit and integration tests
```

## Data Flow

1. Events are produced by various Stella Ops services and carry HLC timestamps.
2. TimelineIndexer Worker (background service within this module) consumes events from the message bus, assigns HLC timestamps, and writes indexed events to the event store.
3. Timeline WebService receives query requests from Platform, CLI, Web, or Replay.
4. Timeline Core executes queries against the indexed event store, applying correlation, service, and time-range filters.
5. Results are returned in HLC-sorted order, with optional critical path analysis computing latency stages between correlated events.

### Unified Audit Aggregator Flow

1. `UnifiedAuditEndpoints` receives `/api/v1/audit/*` requests from Web/CLI clients.
2. `UnifiedAuditAggregationService` retrieves events from `IUnifiedAuditEventProvider`.
3. `HttpUnifiedAuditEventProvider` queries module audit APIs (JobEngine, Policy, EvidenceLocker, Notify) and normalizes heterogeneous payloads into a unified event model.
4. Aggregation computes stats, correlations, anomalies, and export state from the normalized event set.
5. If a module source is unavailable or non-successful, Timeline logs the source failure and continues with partial data instead of failing the unified endpoint.

## Database Schema

Timeline reads from the event store managed by the Eventing infrastructure (PostgreSQL). Key columns queried:

| Column           | Type        | Description                              |
|-----------------|-------------|------------------------------------------|
| `event_id`       | UUID        | Unique event identifier                  |
| `hlc_timestamp`  | BIGINT      | Hybrid Logical Clock timestamp           |
| `correlation_id` | VARCHAR     | Cross-service correlation identifier     |
| `service`        | VARCHAR     | Originating service name                 |
| `event_type`     | VARCHAR     | Event type discriminator                 |
| `payload`        | JSONB       | Event payload                            |
| `created_at`     | TIMESTAMPTZ | Wall-clock ingestion time                |

## Dependencies

| Service/Library           | Purpose                                   |
|--------------------------|-------------------------------------------|
| StellaOps.Eventing        | Event store access and query primitives   |
| StellaOps.HybridLogicalClock | HLC timestamp parsing and comparison   |
| Router                    | Service mesh routing and discovery        |
| Authority                 | JWT/OAuth token validation                |

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/timeline/{correlationId}` | Query events by correlation ID (HLC-ordered). |
| GET | `/api/v1/timeline/{correlationId}/critical-path` | Critical path analysis for a correlation. |
| POST | `/api/v1/timeline/{correlationId}/replay` | Initiate deterministic replay for a correlation. |
| GET | `/api/v1/timeline/replay/{replayId}` | Replay status lookup. |
| POST | `/api/v1/timeline/replay/{replayId}/cancel` | Cancel replay operation. |
| POST | `/api/v1/timeline/{correlationId}/export` | Initiate timeline export. |
| GET | `/api/v1/timeline/export/{exportId}` | Export status lookup. |
| GET | `/api/v1/timeline/export/{exportId}/download` | Download export bundle. |
| GET | `/api/v1/audit/events` | Unified audit event list with filters and cursor paging. |
| GET | `/api/v1/audit/events/{eventId}` | Unified audit event-by-id lookup. |
| GET | `/api/v1/audit/stats` | Unified audit summary statistics. |
| GET | `/api/v1/audit/timeline/search` | Unified audit timeline search. |
| GET | `/api/v1/audit/correlations` | Correlation cluster list. |
| GET | `/api/v1/audit/correlations/{correlationId}` | Correlation cluster details. |
| GET | `/api/v1/audit/anomalies` | Unified anomaly alerts. |
| POST | `/api/v1/audit/anomalies/{alertId}/acknowledge` | Acknowledge anomaly alert. |
| POST | `/api/v1/audit/export` | Request unified audit export. |
| GET | `/api/v1/audit/export/{exportId}` | Unified audit export status. |

## Security Considerations

- **Authentication**: All endpoints require a valid JWT issued by Authority.
- **Tenant isolation**: Queries are scoped to the authenticated tenant; cross-tenant event access is prohibited.
- **Read-only surface**: Timeline exposes only read and replay operations. Event mutation is handled exclusively by TimelineIndexer.
- **Export controls**: Exported event payloads may contain sensitive operational data; exports are audit-logged.
- **Replay determinism**: Replay operations produce identical output given identical input sequences, supporting audit and compliance verification.
- **Unified audit authorization**: `/api/v1/audit/*` read operations require `timeline:read`; acknowledge/export operations require `timeline:write`; tenant context is mandatory.

## TimelineIndexer (Event Ingestion and Indexing)

TimelineIndexer was consolidated into the Timeline module (Sprint 210, 2026-03-04). It provides the write/ingestion side of the CQRS pattern while Timeline provides the read/query side. Both share the same schema domain and live under `src/Timeline/`.

### TimelineIndexer Responsibilities

- **Event ingestion**: Consumes events from NATS/Redis message bus via configurable subscribers.
- **HLC timestamping**: Assigns Hybrid Logical Clock timestamps to establish causal ordering.
- **Event indexing**: Writes indexed events to PostgreSQL via EfCore (compiled model preserved for migration identity).
- **Authorization audit**: Provides audit sink for authorization events.

### Deployable Services

- **TimelineIndexer WebService** (`StellaOps.TimelineIndexer.WebService`): HTTP API for direct event submission and query.
- **TimelineIndexer Worker** (`StellaOps.TimelineIndexer.Worker`): Background service for continuous event ingestion. Separately deployable container for independent scaling.
- **Timeline WebService** (`StellaOps.Timeline.WebService`): Read-only query, analysis, export, and replay API.

This separation allows independent scaling of ingestion and query workloads while sharing domain libraries under a single module boundary.