# Timeline Forensics Guide

The Timeline Indexer service aggregates structured events (scanner runs, policy verdicts, runtime posture, evidence locker activity) so operators can audit changes over time. This guide summarises the event schema, query surfaces, and integration points.

## 1. Event Model

| Field | Description |
|-------|-------------|
| `event_id` | ULID identifying the event. |
| `tenant` | Tenant scope. |
| `timestamp` | UTC ISO-8601 time the event occurred. |
| `category` | Logical grouping (scanner, policy, runtime, evidence). |
| `details` | JSON payload describing the event; contract defined per producer. |
| `trace_id` | Optional distributed trace correlation ID. |

Events are stored append-only with tenant-specific partitions. Producers include Scanner WebService, Policy Engine, Zastava Observer, Evidence Locker, and Notify.

## 2. APIs

- `GET /api/v1/timeline/events` – paginated event stream with filters (tenant, category, time window, correlation IDs).
- `GET /api/v1/timeline/events/{id}` – fetch single event payload.
- `GET /api/v1/timeline/export` – NDJSON export for offline review.

## 3. Query Tips

- Use `category` + `trace_id` to follow a scan-to-policy-to-notification flow.
- Combine `tenant` and `timestamp` filters for SLA audits.
- CLI command `stella timeline list` mirrors the API for automation.

## 4. Integration

- Evidence Locker attaches evidence bundle digests; the console links from timeline to evidence viewer.
- Notifier creates acknowledgement events for incident workflows.
- Offline kits package timeline exports for compliance reviews.

## 5. References

- `docs/modules/telemetry/architecture.md`
- `docs/modules/zastava/architecture.md`
- `docs/modules/export-center/architecture.md`
- `src/TimelineIndexer/StellaOps.TimelineIndexer`