[rickisba]

Motivation

Issue #157 established the canonical src/cacheroute namespace, but its original target tree still mirrored current deployment processes and risked preserving service coupling under a new path.

Issue #159 refines the target architecture around stable contracts, CacheRoute-owned domains, external integrations, deployable services, plugins, and entrypoints.

Changes

• add doc/architecture/package-architecture-rfc.md with the target package responsibilities, vLLM/LMCache integration boundaries, dependency direction, public API policy, packaging policy, versioning policy, migration mapping, phases, and architecture tests;
• add doc/architecture/README.md as the architecture-document index;
• extend AGENTS.md with normative placement rules for future development;
• explicitly mark current root packages as transitional rather than permanent target paths;
• forbid a generic cacheroute.core dumping ground and new root cacheroute_<feature> packages;
• require directory migrations to audit imports, module strings, service entrypoints, Docker/CI/config paths, monkeypatch targets, packaging, and Markdown links.

Scope

Documentation and development-governance only. This PR does not move packages, change runtime behavior, modify the root README, or implement vLLM/LMCache integration code.

Validation

• branch diff contains only AGENTS.md and files under doc/architecture/;
• all new links are local and point to files added by this PR;
• no new functional top-level directory is introduced;
• no existing README introduction is removed.

Refs #159
Refs #157
Refs #141

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f282f165e7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Synchronize package discovery for the architecture directory

Adding this tracked directory makes _discover_root_namespace_packages() discover doc.architecture, but the transitional package list in pyproject.toml remains unchanged. Running python3 -m pytest -q test/test_repository_governance.py therefore fails in test_transitional_explicit_packages_match_root_discovery; reconcile the discovery exclusion and package inventory before merging.

AGENTS.md reference: AGENTS.md:L651-L660

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Retain root packages until their service migrations

In Phase 1, the Scheduler, Proxy, Instance, and KDN implementations still reside in root packages and are not moved until Phase 4, so restricting the wheel to the canonical namespace here would drop the application packages for Phases 1–3. The current pyproject.toml explicitly preserves them until the final migration; defer removal of that transitional package list until the corresponding implementations have moved.

AGENTS.md reference: AGENTS.md:L93-L95

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Split gateway protocols from concrete integrations

This maps the entire kdn_server/gateway tree to LMCache/Redis integrations, but the existing tree also contains the dependency-light LMCacheGateway protocol, capability/profile models, generic negotiation code, and a mock adapter. Following the mapping literally would place the stable extension boundary inside backend-specific integrations; map the protocol/discovery pieces to their cache/plugins owner and reserve integrations.lmcache and integrations.redis for concrete adapters.

AGENTS.md reference: AGENTS.md:L493-L497

Useful? React with 👍 / 👎.