95 lines
3.1 KiB
Markdown
95 lines
3.1 KiB
Markdown
# 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`
|