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

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

Unified Audit Aggregator Flow

UnifiedAuditEndpoints receives /api/v1/audit/* requests from Web/CLI clients.
UnifiedAuditAggregationService retrieves events from IUnifiedAuditEventProvider.
HttpUnifiedAuditEventProvider queries module audit APIs (JobEngine, Policy, EvidenceLocker, Notify) and normalizes heterogeneous payloads into a unified event model.
Aggregation computes stats, correlations, anomalies, and export state from the normalized event set.
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.

8.7 KiB Raw Blame History