stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
ac544c00643ca073d363fc53f7e3ce2ce4c2f060
git.stella-ops.org/docs/modules/timeline/architecture.md

8.7 KiB
Raw Blame History

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.