save progress

docs/modules/timelineindexer/architecture.md

@@ -0,0 +1,74 @@
+# 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`