Status: Current developer navigation for CacheRoute maintainers.
This handbook is for maintainers, contributors, and review agents who need to change CacheRoute without changing undocumented public or structural behavior accidentally.
Start here, then read the chapter that owns the surface you are changing. Keep one detailed source of truth for each topic and link to it rather than copying large maintained documents.
CacheRoute is in a Transitional repository state: root packages still run the historical Scheduler, Proxy, Instance, KDN, Client, UI, and utility components, while dependency-light canonical foundations live under src/cacheroute/. PR #183 observability propagation and Proxy-local stage collection are Current. Broader Issue #141 observability remains incomplete.
- Architecture and evolution
- Package and module map
- Public API and data-model catalog
- Runtime flows
- Configuration and interfaces
- Compatibility and migrations
- Development and validation
- Documentation governance
- Glossary
| Status | Meaning |
|---|---|
| Historical | Previously important context that should not be treated as a current target. |
| Current | Implemented in the repository and validated by source or tests. |
| Transitional | Implemented compatibility behavior that remains while migration continues. |
| Target / Accepted | Accepted direction that may not be fully implemented yet. |
| Proposed | Investigatory or roadmap material that is not accepted current behavior. |
| Deprecated | Supported only for compatibility and expected to be removed after an approved milestone. |
| Source | Scope | Authority |
|---|---|---|
| Root README | High-level project introduction, quick start, component links. | Current overview only. |
| Package architecture RFC | Ownership boundaries and dependency direction. | Maintained architecture source. |
| Observability v1 | Maintained observability design and schema intent. | Maintained design source. |
| Developer handbook | Navigation and summarized developer reference. | Summary; link to detailed owners. |
| Component READMEs | Focused operational behavior for root components. | Current component operations where source agrees. |
| Environment documentation | Environment and deployment setup. | Deployment source of truth. |
| Research documents | Temporary investigation and design notes. | Non-authoritative when a maintained architecture document owns the same subject. |
| Blog documents | Historical milestones and changelog notes. | Historical context. |
| Approved GitHub Issues | Accepted but not implemented design. | Target / Accepted until source and tests implement it. |
| Task | Read first |
|---|---|
| Change package ownership or dependency direction | Package and module map, Package architecture RFC |
| Change public models, enums, or imports | Public API and data-model catalog |
| Change request flow, headers, queues, or observability stages | Runtime flows |
| Change CLI, environment variables, endpoints, or request fields | Configuration and interfaces |
| Change shims or migration state | Compatibility and migrations |
| Prepare PR evidence | Development and validation |
Update the relevant handbook chapter in the same PR when a documented public or structural surface changes. Keep root README changes minimal. Do not describe unmerged or absent features as Current.