# component_architecture_timelineindexer.md - **Stella Ops TimelineIndexer** (2025Q4)

> 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
 ├─ StellaOps.TimelineIndexer.WebService/     # Query API
 ├─ StellaOps.TimelineIndexer.Worker/         # Event consumer
 └─ StellaOps.TimelineIndexer.Tests/
```

---

## 2) External dependencies

* **PostgreSQL** - Event storage with time-series indexes
* **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?subject={id}&from={date}&to={date}  → { events[] }
GET  /timeline/{eventId}                            → { event }
GET  /timeline/stats?subject={id}                   → { statistics }

GET  /healthz | /readyz | /metrics
```

---

## Related Documentation

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