These guides explain both how Insights works and why its boundaries exist. Start with the introduction, continue to architecture, then use the task-oriented guides as needed.
| Guide | Use it when |
|---|---|
| Introduction | You are new to the project and want the visual mental model |
| Architecture | You need the system map and request/job lifecycles |
| Invariants | You are changing behavior and need the rules that must remain true |
| API authentication | You are working on credentials, admins, or webhook tokens |
| Operations | You are deploying, bootstrapping, or on call |
| Frontend contract | You are building a browser client against this API |
| Secret providers | You are configuring or adding a credential backend |
| Queue workers and scheduling | You are changing clocks, queues, workers, or scaling |
| Test reference | You need to know what the suite covers, or why it will not run |
| Testing collection | You need to run collection immediately and inspect it |
| Adding a job | You are implementing another platform collector |
| Metric collection | You need to understand snapshots, rolling windows, and retention |
| Watermarks | You need a focused explanation of double-count prevention |
| Troubleshooting | Something is running incorrectly |
| Glossary | A project term is unfamiliar |
Architecture decisions live under decisions/. They preserve the reasoning
behind important choices so future changes retain the system's correctness guarantees.
#icicle-insights# #documentation-index# #developer-documentation#