component_architecture_timelineindexer.md - Stella Ops TimelineIndexer (2026Q1)

Timeline event indexing and query service.

Scope. Implementation-ready architecture for TimelineIndexer: indexing and querying timeline events for vulnerability findings, scans, and policy evaluations.

0) Mission & boundaries

Mission. Provide fast, indexed access to timeline events across all StellaOps services. Enable efficient querying of vulnerability history, scan timelines, and policy evaluation trails.

Boundaries.

TimelineIndexer indexes events; it does not generate them.
Events are received from event streams (NATS, Valkey).
Supports time-range queries with filtering.

1) Solution & project layout

src/TimelineIndexer/StellaOps.TimelineIndexer/
 |- StellaOps.TimelineIndexer.Core/           # Event models, indexing logic
 |- StellaOps.TimelineIndexer.Infrastructure/ # Storage adapters and DAL
 |- StellaOps.TimelineIndexer.WebService/     # Query API
 |- StellaOps.TimelineIndexer.Worker/         # Event consumer
 `- StellaOps.TimelineIndexer.Tests/

1.1 Persistence implementation (2026-02-22)

TimelineIndexer persistence uses EF Core 10 with database-first scaffolded models.
Generated artifacts are stored in:
- src/TimelineIndexer/StellaOps.TimelineIndexer/StellaOps.TimelineIndexer.Infrastructure/EfCore/Context
- src/TimelineIndexer/StellaOps.TimelineIndexer/StellaOps.TimelineIndexer.Infrastructure/EfCore/Models
- src/TimelineIndexer/StellaOps.TimelineIndexer/StellaOps.TimelineIndexer.Infrastructure/EfCore/CompiledModels
Store adapters (TimelineEventStore, TimelineQueryStore) run through TimelineIndexerDataSource tenant-scoped sessions, preserving app.current_tenant and RLS behavior.
Manual model corrections (enum mapping and FK relationship configuration) are implemented in partial files, so scaffolded files remain regeneratable.
Runtime context initialization uses the static compiled model module:
- options.UseModel(TimelineIndexerDbContextModel.Instance)

2) External dependencies

PostgreSQL - Event storage with time-series indexes
EF Core 10 + Npgsql provider - DAL and model mapping for timeline schema
NATS/Valkey - Event stream consumption
Authority - Authentication

3) Contracts & data model

3.1 TimelineEvent

{
  "eventId": "evt-2025-01-15-abc123",
  "eventType": "scan.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "tenantId": "tenant-xyz",
  "subjectId": "image:sha256:abc123",
  "payload": { /* event-specific data */ }
}

4) REST API

GET  /timeline?eventType=&source=&correlationId=&traceId=&severity=&since=&after=&limit=
GET  /timeline/{eventId}
GET  /timeline/{eventId}/evidence
POST /timeline/events

# Gateway microservice aliases
GET  /api/v1/timeline
GET  /api/v1/timeline/{eventId}
GET  /api/v1/timeline/{eventId}/evidence
POST /api/v1/timeline/events

GET  /healthz | /readyz | /metrics

Signals: ../signals/architecture.md
Scanner: ../scanner/architecture.md

3.1 KiB Raw Blame History