docs(modularization): add current-state architecture doc (#27)#1636
Merged
Conversation
…se-6 end state (#27) Adds `docs/modularization/architecture.md` as the authoritative source-of-truth for the post-Phase-6 modularization end state. Scope is current-state only; the existing `README.md` / `roadmap.md` / `target-domain-map.md` stay as historical plan references. The document covers, based on `origin/main @ 28a9f53`: - Executive summary with the Phase 0→6 PR + merge commit table. - Per-domain inventory for all 12 backend domains (identity / governance / model_platform / marketplace / knowledge_base / indexing / retrieval / knowledge_graph / conversation / agent_runtime / evaluation / web_access), listing DB symbols, schemas, services, consumer-owned Protocols, and API routes for each. - Top-level infrastructure modules (`aperag/app.py`, `aperag/db/base.py`, `aperag/schema/common.py` with its strict shared-primitive admission criterion, `aperag/llm/`, etc.). - The canonical rules governing every cross-domain seam: direct import vs `Protocol + DI` (two subclasses: legacy-not-moved-yet vs standalone-infra permanent); dual-hook Scenario A re-export with the `sys.modules.get(...)` trick that lets domain schemas rebind onto `aperag.schema.view_models` without tripping G1; per-domain `AuthenticatedUser(Protocol)` + the User write hierarchy (identity-owned facade > inline text SQL > forbidden cross-domain User ORM). - Boundary gates catalog with the exact pytest function backing each of G1 / G4 / G10 / G14 / G15 / G16 / G17 / G18 alt / G19 plus the KB consumer-owned Protocol + DI smoke tests. - Runtime-seams steady state: the two permanent `CRITICAL_WIRINGS` entries (`conversation.bot_service._quota_ops` and `agent_runtime.runtime._prompt_template_ops`), and why `dispatch_fn` is intentionally excluded. - Legacy-shim inventory by file (service, view, db.models, view_models, top-level `agent_runtime` / `evaluation_v2`). - Historical index linking the phase2/3/4/5 breaking-changes docs. - Future candidates (legacy shim hard-delete, `_enum_column` consolidation, `AuthenticatedUser` shared Protocol, residual legacy service/view extraction, `web_access` deepening, URL prefix unification, deeper SME write-ups) listed but explicitly marked as non-commitments. Doc-only change per msg=d54eb823 scope lock (no code or test changes). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…re doc (#27) Per SME correction in the #27 thread (chenyexuan msg=e1f70eaa, architect msg=c1face5c, PM msg=288cc691), the phrase "2 permanent CRITICAL_WIRINGS" only refers to the Phase 5 G18-alt registry. G17 still holds 7 live entries (4 KB consumer-owned Protocol slots + 3 identity `*InitOps` adapters) and has not been collapsed by Phase 5/6. Adjustments: - Executive summary (Section 1) now states "two separate runtime-wiring registries": G17 with 7 entries + G18-alt with 2 permanent entries, instead of the ambiguous "2 permanent CRITICAL_WIRINGS" phrasing. - Section 5 opens with a precision paragraph that calls out the two registries explicitly and warns against collapsing them into a single "2-entry" summary. - Section 5.1 header renamed "The Phase 5 permanent two-entry registry (G18 alt)" so the scope is unambiguous. - Section 5.2 expanded to explain why G18 alt collapsed to two over the Phase 5/6 run, and why G17 did not collapse: KB `_marketplace_ops` / `_search_pipeline_ops` / `_quota_ops` sit on standalone-infra providers that were never in domain-move scope; `_marketplace_collection_ops` stays as a narrow consumer-Protocol seam (with a candidate simplification in Section 8); identity `*InitOps` adapters still host the identity-side contract and have no retirement path without a separate design decision. No other sections changed. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Per architect Section 8 audit (msg=5ce5f260) + PM guidance (msg=19eb93b6), restructure Section 8 into: - 8.1 High-value candidates (F1/F2/F3) with a paragraph each: * Cross-domain integration test coverage * `aperag/service/*.py` legacy shim hard-delete audit * `aperag/views/*.py` migration/retirement map - 8.2 Compressed catalog (F4–F13) — one-line entries, effort/value tags, no roadmap tense: * F4 `_enum_column` helper consolidation * F5 `AuthenticatedUser(Protocol)` consolidation * F6 `aperag/app.py` DI wire-up extraction * F7 `aperag/schema/view_models.py` residual re-exports * F8 G-gate to boundary test mapping * F9 `aperag/agent_runtime/` + `aperag/evaluation_v2/` shim deletion * F10 `aperag/platform/` layering * F11 `web_access` depth * F12 `/api/v1` vs `/api/v2` unification * F13 Deeper SME write-up for indexing/retrieval/knowledge_graph Language stays "may be worth doing" (PM hard boundary msg=19eb93b6: don't write future candidates as "已决定要做"). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…h_pipeline_service classification (#27) Independent CR corrections from architect (msg=c1face5c / 20:21 block) and chenyexuan (msg=ef864605) both flagged: 1. Section 2.1 evaluation row listed `ChatSessionOps` and `AgentTurnDispatchOps` as Consumer ports, but both classes have zero runtime callers (seeded in Phase 5 5-S1 on a pre-rebase assumption that chat_service / agent_runtime would stay legacy; after 5-S4b + 5-S5b domain moves + `9162ec4` rebase, `worker::dispatch_fn` switched to late-import direct cross-domain access and the seams were never wired). Dead Protocol literals only; shape identical to `ChatDocumentOps` before Phase 6 entry 4 deleted it. 2. Section 6.1 classified `aperag/service/search_pipeline_service.py` as "standalone-infra permanent" but that classification was never locked by a Phase 6 canonical decision — only `quota_service` and `prompt_template_service` got that lock (Phase 6 entry 3, msg=ebce5e1e). `search_pipeline_service` classification is pending. Fixes: - Section 2.1 evaluation Consumer ports narrowed to `AuthenticatedUser` with a new footnote that documents why the Protocol class-defs persist. - Section 6.1 `search_pipeline_service.py` line re-labelled "legacy provider for KB `SearchPipelineOps`; classification … pending future decision"; `quota_service` / `prompt_template_service` lines upgraded to "Phase 6 entry 3 canonical" wording for symmetry. - Section 5.2 parallel statement softened: `_search_pipeline_ops` no longer described as "standalone-infra or cross-cutting"; the classification-pending status is spelled out. - Section 8.2 gains two new entries: F14 (dead Protocol class literal sweep for `ChatSessionOps` + `AgentTurnDispatchOps`) and F15 (`search_pipeline_service` classification decision). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…versation topology (#27) Per architect refined correction (msg=25eaffc1) and chenyexuan P5-1 patch (msg=ef864605 + PM msg=0c7486de): - Section 2.1 evaluation row now keeps `ChatSessionOps` and `AgentTurnDispatchOps` visible in the Consumer ports cell but explicitly annotates them as "dead Protocol literals (zero runtime callers — see footnote and Section 8 F14)". Matches the architect's preferred treatment: do not delete from the cell (reader would wonder why `ports.py` still has class defs); annotate inline so the reader sees both the file reality and the architectural status in one glance. - New Section 2.5 `conversation` intra-domain dependency topology captures the six-service call graph (bot_service + turn_feedback_service as leaves; chat_title_service / chat_collection_service / chat_document_service / chat_service as the dependency-carrying services) plus the late-import rule used by agent_runtime and evaluation consumers to avoid evaluation → agent_runtime → conversation module-import-time cycles. Domain-edge map renumbered to Section 2.6. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Why now
Phase 6 merge left three docs (`README.md` / `roadmap.md` / `target-domain-map.md`) as the de-facto entry point, but all three are pre-Phase-6 historical plan docs. task #27 (`启动发射！`) asked the supporting architect to write a complete current-state architecture doc so that the 12-domain layout, the 20 boundary tests, the 2 permanent CRITICAL_WIRINGS, and the canonical rules codified over the 49-commit Phase 3+4+5 run (plus the 5-commit Phase 6 cleanup) have one authoritative reference.
What the doc covers (8 sections per PM spec)
Inputs integrated
Test plan
🤖 Generated with Claude Code