# 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/        # REST API (ASP.NET Core)
    Endpoints/
      TimelineEndpoints.cs              # Core timeline query endpoints
      ExportEndpoints.cs                # Event export endpoints
      ReplayEndpoints.cs                # Deterministic replay endpoints
    Program.cs                          # Host configuration
  StellaOps.Timeline.Core/              # Query service and models
    ITimelineQueryService.cs            # Core query interface
    TimelineQueryService.cs             # Query implementation
    Models/
      TimelineEvent.cs                  # Event with HLC timestamp + correlation ID
      CriticalPathResult.cs             # Stages with durations
      TimelineQueryOptions.cs           # Filters + pagination
```

## Data Flow

1. Events are produced by various Stella Ops services and carry HLC timestamps.
2. TimelineIndexer (separate module) ingests and indexes these events into 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.

## 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    | `/timeline/by-correlation/{correlationId}`     | Query events by correlation ID (HLC-ordered)     |
| GET    | `/timeline/critical-path/{correlationId}`      | Critical path analysis with latency stages       |
| GET    | `/timeline/by-service/{service}`               | Service-filtered timeline view                   |
| POST   | `/timeline/export`                             | Export events matching query criteria             |
| POST   | `/timeline/replay`                             | Deterministic replay of an event sequence        |

## 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.

## Relationship to TimelineIndexer

Timeline and TimelineIndexer are separate deployable services with distinct responsibilities:

- **TimelineIndexer**: Consumes events from the message bus, assigns HLC timestamps, and writes indexed events to the event store.
- **Timeline**: Reads from the event store and serves query, analysis, export, and replay requests.

This separation allows independent scaling of ingestion and query workloads.