# 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

```json
{
  "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
```

---

## Related Documentation

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