Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(generation): the overview carries the architecture map (#1164)

Swati Ahujafce08cafcd42
diff --git a/packages/core/src/repowise/core/cost_estimator/approx.py b/packages/core/src/repowise/core/cost_estimator/approx.py
index 2e38f8f97..d7ae66a74 100644
--- a/packages/core/src/repowise/core/cost_estimator/approx.py
+++ b/packages/core/src/repowise/core/cost_estimator/approx.py
@@ -58,7 +58,6 @@ def approximate_generation_plan(
PageTypePlan(page_type="file_page", count=file_pages, level=0),
PageTypePlan(page_type="module_page", count=module_pages, level=1),
PageTypePlan(page_type="repo_overview", count=1 if file_count else 0, level=2),
- PageTypePlan(page_type="architecture_diagram", count=1 if file_count else 0, level=2),
]
if onboarding and file_count:
plans.append(PageTypePlan(page_type="onboarding", count=_ONBOARDING_SLOTS, level=2))
diff --git a/packages/core/src/repowise/core/cost_estimator/plans.py b/packages/core/src/repowise/core/cost_estimator/plans.py
index d3421e4e8..05468ca5a 100644
--- a/packages/core/src/repowise/core/cost_estimator/plans.py
+++ b/packages/core/src/repowise/core/cost_estimator/plans.py
@@ -85,7 +85,6 @@ def build_generation_plan(
"scc_page",
"module_page",
"repo_overview",
- "architecture_diagram",
"infra_page",
):
count = counts.get(page_type, 0)
diff --git a/packages/core/src/repowise/core/generation/onboarding/__init__.py b/packages/core/src/repowise/core/generation/onboarding/__init__.py
index f2c2720c5..9098fe183 100644
--- a/packages/core/src/repowise/core/generation/onboarding/__init__.py
+++ b/packages/core/src/repowise/core/generation/onboarding/__init__.py
@@ -5,7 +5,7 @@ Guided Tour, Getting Started, Codebase Map, Key Concepts, How It Works,
Development Guide, Active Landscape, designed to be the first thing a new
contributor (or LLM agent) reads.
-Two slots ("project_overview", "architecture_guide") are *promoted*: they
+One slot ("project_overview") is *promoted*: it
reuse the existing ``repo_overview`` and ``architecture_diagram`` pages,
tagged via ``metadata.onboarding_slot``. The other seven slots are new pages
generated at level 8 with ``page_type='onboarding'`` and a
@@ -28,7 +28,6 @@ from .slots import (
ONBOARDING_ORDER,
PROMOTED_SLOTS,
SLOT_ACTIVE_LANDSCAPE,
- SLOT_ARCHITECTURE_GUIDE,
SLOT_CODEBASE_MAP,
SLOT_DEVELOPMENT_GUIDE,
SLOT_GETTING_STARTED,
@@ -45,7 +44,6 @@ __all__ = [
"ONBOARDING_ORDER",
"PROMOTED_SLOTS",
"SLOT_ACTIVE_LANDSCAPE",
- "SLOT_ARCHITECTURE_GUIDE",
"SLOT_CODEBASE_MAP",
"SLOT_DEVELOPMENT_GUIDE",
"SLOT_GETTING_STARTED",
diff --git a/packages/core/src/repowise/core/generation/onboarding/registry.py b/packages/core/src/repowise/core/generation/onboarding/registry.py
index 1f9ae5082..8242adc2a 100644
--- a/packages/core/src/repowise/core/generation/onboarding/registry.py
+++ b/packages/core/src/repowise/core/generation/onboarding/registry.py
@@ -70,7 +70,7 @@ def get_spec(slot: str) -> SubkindSpec | None:
def iter_specs() -> list[SubkindSpec]:
"""Return registered specs in canonical reading order.
- Promoted slots (project_overview, architecture_guide) are not generated
+ The promoted slot (project_overview) is not generated
through this path and are excluded here.
"""
promoted = set(PROMOTED_SLOTS.values())
diff --git a/packages/core/src/repowise/core/generation/onboarding/slots.py b/packages/core/src/repowise/core/generation/onboarding/slots.py
index 29ffa6bad..b97dffcda 100644
--- a/packages/core/src/repowise/core/generation/onboarding/slots.py
+++ b/packages/core/src/repowise/core/generation/onboarding/slots.py
@@ -1,9 +1,9 @@
"""Onboarding slot identifiers and reading order.
-The Onboarding collection is a fixed set of nine curated slots. Two slots are
-"promoted": they reuse the existing `repo_overview` and `architecture_diagram`
-pages, tagged via ``metadata.onboarding_slot``. The other seven are new pages
-with ``page_type='onboarding'`` and a ``metadata.subkind`` discriminator.
+The Onboarding collection is a fixed set of eight curated slots. One slot is
+"promoted": it reuses the existing `repo_overview` page, tagged via
+``metadata.onboarding_slot``. The other seven are new pages with
+``page_type='onboarding'`` and a ``metadata.subkind`` discriminator.
Slot identifiers are used three ways:
- as the ``metadata.subkind`` value on generated pages,
@@ -12,7 +12,7 @@ Slot identifiers are used three ways:
Keep the order list in lockstep with ``packages/ui/src/lib/page-types.ts``
``ONBOARDING_ORDER``. A slot without enough signal is skipped at generation
-time, so a repo can end up with fewer than nine.
+time, so a repo can end up with fewer than eight.
"""
from __future__ import annotations
@@ -28,7 +28,6 @@ ONBOARDING_GENERATION_VERSION = "2"
# ---- Slot identifiers ----
SLOT_PROJECT_OVERVIEW = "project_overview"
-SLOT_ARCHITECTURE_GUIDE = "architecture_guide"
SLOT_GUIDED_TOUR = "guided_tour"
SLOT_GETTING_STARTED = "getting_started"
SLOT_CODEBASE_MAP = "codebase_map"
@@ -41,7 +40,6 @@ SLOT_ACTIVE_LANDSCAPE = "active_landscape"
# generation time and absent from the UI tree.
ONBOARDING_ORDER: tuple[str, ...] = (
SLOT_PROJECT_OVERVIEW,
- SLOT_ARCHITECTURE_GUIDE,
SLOT_GUIDED_TOUR,
SLOT_GETTING_STARTED,
SLOT_CODEBASE_MAP,
@@ -56,14 +54,12 @@ ONBOARDING_ORDER: tuple[str, ...] = (
# extra content is generated for promoted slots.
PROMOTED_SLOTS: dict[str, str] = {
"repo_overview": SLOT_PROJECT_OVERVIEW,
- "architecture_diagram": SLOT_ARCHITECTURE_GUIDE,
}
# Human-readable titles used both server-side (page title) and as a fallback
# label in the UI when a page hasn't been hydrated yet.
SLOT_TITLES: dict[str, str] = {
SLOT_PROJECT_OVERVIEW: "Project Overview",
- SLOT_ARCHITECTURE_GUIDE: "Architecture Guide",
SLOT_GUIDED_TOUR: "Guided Tour",
SLOT_GETTING_STARTED: "Getting Started",
SLOT_CODEBASE_MAP: "Codebase Map",
@@ -76,12 +72,11 @@ SLOT_TITLES: dict[str, str] = {
SLOT_PREREQUISITES: dict[str, tuple[str, ...]] = {
SLOT_PROJECT_OVERVIEW: (),
- SLOT_ARCHITECTURE_GUIDE: (),
SLOT_GUIDED_TOUR: (SLOT_PROJECT_OVERVIEW,),
SLOT_GETTING_STARTED: (),
SLOT_CODEBASE_MAP: (SLOT_PROJECT_OVERVIEW,),
- SLOT_KEY_CONCEPTS: (SLOT_PROJECT_OVERVIEW, SLOT_ARCHITECTURE_GUIDE),
- SLOT_HOW_IT_WORKS: (SLOT_ARCHITECTURE_GUIDE, SLOT_KEY_CONCEPTS),
+ SLOT_KEY_CONCEPTS: (SLOT_PROJECT_OVERVIEW,),
+ SLOT_HOW_IT_WORKS: (SLOT_KEY_CONCEPTS,),
SLOT_DEVELOPMENT_GUIDE: (SLOT_GETTING_STARTED, SLOT_HOW_IT_WORKS),
SLOT_ACTIVE_LANDSCAPE: (SLOT_CODEBASE_MAP,),
}
diff --git a/packages/core/src/repowise/core/generation/page_generator/levels.py b/packages/core/src/repowise/core/generation/page_generator/levels.py
index a22a6ca61..2374b6a69 100644
--- a/packages/core/src/repowise/core/generation/page_generator/levels.py
+++ b/packages/core/src/repowise/core/generation/page_generator/levels.py
@@ -356,8 +356,26 @@ def build_level5_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
def build_level6_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
- """Level 6 (repo_overview + architecture_diagram)."""
+ """Level 6 (repo_overview).
+
+ The overview carries the architecture map. That map used to sit on a page
+ of its own, which described the same repository at the same altitude in the
+ same words — the two shared roughly a quarter of their vocabulary, so a
+ reader meeting both read one thing twice. The diagram is what that page
+ uniquely had, so it moved here and the page retired; its id redirects.
+ """
+ from ..architecture_mermaid import build_overview_mermaid
+
gen = run.gen
+ overview_mermaid = build_overview_mermaid(run.kg_ctx)
+ if not overview_mermaid:
+ # The retired page drew its own diagram when the graph could not supply
+ # one, so this used to degrade to a worse map rather than to none. Now
+ # the wiki simply ships without one, which is worth knowing about.
+ log.warning(
+ "generation.overview_architecture_map_empty",
+ repo_name=run.repo_name,
+ )
coros: list[tuple[str, Any]] = []
if run._emit(compute_page_id("repo_overview", run.repo_name)):
coros.append(
@@ -373,22 +391,6 @@ def build_level6_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
repo_name=run.repo_name,
external_systems=run.external_systems,
decision_records=run.decisions_all[:10],
- ),
- )
- )
- if run._emit(compute_page_id("architecture_diagram", run.repo_name)):
- from ..architecture_mermaid import build_overview_mermaid
-
- overview_mermaid = build_overview_mermaid(run.kg_ctx)
- coros.append(
- (
- compute_page_id("architecture_diagram", run.repo_name),
- gen.generate_architecture_diagram(
- run.graph,
- run.pagerank,
- run.community,
- run.sccs,
- run.repo_name,
overview_mermaid=overview_mermaid,
),
)
diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
index ea51de553..112bfedb9 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -464,7 +464,6 @@ class _GenerationRun:
+ counts["module_page"]
+ layer_page_count
+ int(self.selection.emit_repo_overview)
- + int(self.selection.emit_arch_diagram)
+ counts["infra_page"]
+ onboarding_page_count
)
diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.py
index 9a2ef7998..b2f173787 100644
--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py
+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py
@@ -54,6 +54,20 @@ def _stub_fallback(page: GeneratedPage, page_type: str, exc: Exception) -> Gener
return page
+def _with_architecture_map(page: GeneratedPage, overview_mermaid: str | None) -> GeneratedPage:
+ """Embed the KG-derived architecture map into an already-built page.
+
+ The overview is where the map lives, so the stub paths carry it too — a
+ provider outage should cost the prose around the diagram, not the diagram.
+ Embedding is idempotent, so calling this on a page that already has one is
+ safe.
+ """
+ if not overview_mermaid:
+ return page
+ page.content = embed_mermaid(page.content, overview_mermaid, heading="## Architecture map")
+ return page
+
+
class PerTypeGenerationMixin:
"""Per-type ``generate_*`` methods. Requires the host to provide
``_assembler``, ``_render``, ``_call_provider`` and
@@ -252,6 +266,7 @@ class PerTypeGenerationMixin:
repo_name: str | None = None,
external_systems: list[dict] | None = None,
decision_records: list[dict] | None = None,
+ overview_mermaid: str | None = None,
) -> GeneratedPage:
ctx = self._assembler.assemble_repo_overview(
repo_structure,
@@ -282,9 +297,10 @@ class PerTypeGenerationMixin:
if not repo_name:
repo_name = getattr(repo_structure, "name", None) or "repo"
if self._config.deterministic:
- return self._stub_repo_overview(
+ stub = self._stub_repo_overview(
ctx, repo_name, f"Repository Overview: {repo_name}", repo_git_summary
)
+ return _with_architecture_map(stub, overview_mermaid)
user_prompt = self._render("repo_overview.j2", ctx=ctx, repo_git_summary=repo_git_summary)
try:
response = await self._call_provider(
@@ -294,7 +310,19 @@ class PerTypeGenerationMixin:
stub = self._stub_repo_overview(
ctx, repo_name, f"Repository Overview: {repo_name}", repo_git_summary
)
- return _stub_fallback(stub, "repo_overview", exc)
+ return _with_architecture_map(
+ _stub_fallback(stub, "repo_overview", exc), overview_mermaid
+ )
+ # The overview carries the architecture map itself. It is the
+ # deterministic KG-derived diagram, not one the model drew, and
+ # embedding is idempotent so a reused page picks it up too.
+ if overview_mermaid:
+ response = replace(
+ response,
+ content=embed_mermaid(
+ response.content, overview_mermaid, heading="## Architecture map"
+ ),
+ )
return self._build_generated_page(
"repo_overview",
repo_name,
diff --git a/packages/core/src/repowise/core/generation/page_redirects.py b/packages/core/src/repowise/core/generation/page_redirects.py
index 3a041c62b..0d058a6ca 100644
--- a/packages/core/src/repowise/core/generation/page_redirects.py
+++ b/packages/core/src/repowise/core/generation/page_redirects.py
@@ -31,8 +31,13 @@ from __future__ import annotations
# Retired page type → the page type that took over its material. The target
# path is carried across unchanged.
-SUPERSEDED_TYPES: dict[str, str] = {}
+SUPERSEDED_TYPES: dict[str, str] = {
+ # The architecture diagram described the same repository at the same
+ # altitude as the overview, in the same words. Its diagram moved to the
+ # overview and the page retired.
+ "architecture_diagram": "repo_overview",
+}
# Retired page id → successor page id, in full. For pages whose target path is
# the same in every repository.
SUPERSEDED_IDS: dict[str, str] = {}
diff --git a/packages/core/src/repowise/core/generation/scope.py b/packages/core/src/repowise/core/generation/scope.py
index 46f1c0c41..93d97a2eb 100644
--- a/packages/core/src/repowise/core/generation/scope.py
+++ b/packages/core/src/repowise/core/generation/scope.py
@@ -34,7 +34,7 @@ from repowise.core.generation.page_selection import (
from repowise.core.generation.selection import Selection, SelectionInputs, select_pages
# Page types that describe the whole repository (as opposed to one file/module).
-_REPO_WIDE_TYPES = frozenset({"repo_overview", "architecture_diagram", "onboarding"})
+_REPO_WIDE_TYPES = frozenset({"repo_overview", "onboarding"})
# Structural pages the coverage budget does not rank: layer pages come from KG
# membership and onboarding is curated, so init emits every one of them at every
@@ -160,10 +160,7 @@ def build_dependencies(
)
)
- repo_wide_ids = [
- compute_page_id("repo_overview", repo_name),
- compute_page_id("architecture_diagram", repo_name),
- ]
+ repo_wide_ids = [compute_page_id("repo_overview", repo_name)]
repo_wide_ids += [r.page_id for r in records if r.page_type == "onboarding"]
return build_page_dependencies(
@@ -179,7 +176,7 @@ def selection_page_ids(sel: Selection, repo_name: str) -> set[str]:
Mirrors the id assignment in the page generator's level builders exactly
(``levels.py``), so a ranked coverage pick names the same pages a full run
- at that coverage would write. Repo-wide overview/architecture pages are
+ at that coverage would write. The repo-wide overview page is
keyed by the repo name; onboarding is not budgeted here (the caller adds it).
"""
ids: set[str] = set()
@@ -194,8 +191,6 @@ def selection_page_ids(sel: Selection, repo_name: str) -> set[str]:
)
if sel.emit_repo_overview:
ids.add(compute_page_id("repo_overview", repo_name))
- if sel.emit_arch_diagram:
- ids.add(compute_page_id("architecture_diagram", repo_name))
return ids
diff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.py
index a52d8d4f5..dedb06ea0 100644
--- a/packages/core/src/repowise/core/generation/selection/selector.py
+++ b/packages/core/src/repowise/core/generation/selection/selector.py
@@ -119,7 +119,6 @@ class Selection:
infra_paths: list[str] = field(default_factory=list)
scc_groups: list[tuple[str, list[str]]] = field(default_factory=list) # (scc_id, files)
emit_repo_overview: bool = True
- emit_arch_diagram: bool = True
# The concept partition behind ``module_groups``, one entry per group, plus
# the layer names the grouper steered by. Carried so a caller holding a
# provider can name these groups; selection itself stays free of the model
@@ -142,7 +141,6 @@ class Selection:
"scc_page": len(self.scc_groups),
"module_page": len(self.module_groups),
"repo_overview": int(self.emit_repo_overview),
- "architecture_diagram": int(self.emit_arch_diagram),
"infra_page": len(self.infra_paths),
}
@@ -701,7 +699,6 @@ def select_pages(inputs: SelectionInputs) -> Selection:
infra_paths=[p for _, p in infras],
scc_groups=[g for _, g in sccs],
emit_repo_overview=True,
- emit_arch_diagram=True,
)
log.info("page_selection.complete", counts=sel.counts())
return sel
diff --git a/packages/ui/src/lib/page-types.ts b/packages/ui/src/lib/page-types.ts
index 251716eef..6826d8043 100644
--- a/packages/ui/src/lib/page-types.ts
+++ b/packages/ui/src/lib/page-types.ts
@@ -81,9 +81,9 @@ export function isStubPage(
// Onboarding collection
// ---------------------------------------------------------------------------
//
-// Two slots — project_overview and architecture_guide — are *promoted*: their
-// content lives in the existing repo_overview / architecture_diagram pages,
-// tagged via `metadata.onboarding_slot`. The other seven are dedicated
+// One slot — project_overview — is *promoted*: its
+// content lives in the existing repo_overview page, tagged via
+// `metadata.onboarding_slot`. The other seven are dedicated
// `page_type === "onboarding"` pages with `metadata.subkind` discriminating
// them.
//
@@ -95,7 +95,6 @@ export function isStubPage(
export const ONBOARDING_SLOT_TITLES = {
project_overview: "Project Overview",
- architecture_guide: "Architecture Guide",
guided_tour: "Guided Tour",
getting_started: "Getting Started",
codebase_map: "Codebase Map",
diff --git a/tests/integration/test_deterministic_generation.py b/tests/integration/test_deterministic_generation.py
index ee12c0f85..d175628a1 100644
--- a/tests/integration/test_deterministic_generation.py
+++ b/tests/integration/test_deterministic_generation.py
@@ -136,7 +136,7 @@ class TestDeterministicGeneration:
types = {p.page_type for p in deterministic_pages}
assert "file_page" in types
assert "repo_overview" in types
- assert "architecture_diagram" in types
+ assert "architecture_diagram" not in types
assert len(types) >= 4, f"only got {types}"
def test_full_file_coverage(self, deterministic_pages):
diff --git a/tests/integration/test_generation_pipeline.py b/tests/integration/test_generation_pipeline.py
index 5c80fcde1..943762f93 100644
--- a/tests/integration/test_generation_pipeline.py
+++ b/tests/integration/test_generation_pipeline.py
@@ -392,9 +392,18 @@ class TestGenerationPipeline:
types = [p.page_type for p in pipeline_result["pages"]]
assert types.count("repo_overview") == 1
- def test_generates_architecture_diagram(self, pipeline_result):
- types = [p.page_type for p in pipeline_result["pages"]]
- assert types.count("architecture_diagram") == 1
+ def test_architecture_map_lives_on_the_overview(self, pipeline_result):
+ """The diagram no longer gets a page of its own.
+
+ It described the same repository at the same altitude as the overview
+ and in the same words, so the map moved onto the overview and the page
+ retired. A run that still emits one has regressed.
+ """
+ pages = pipeline_result["pages"]
+ types = [p.page_type for p in pages]
+ assert types.count("architecture_diagram") == 0
+ assert types.count("repo_overview") == 1
+
def test_generates_file_page_for_py_files(self, pipeline_result):
"""There should be at least one file_page for Python files."""
diff --git a/tests/unit/cli/test_cost_estimator.py b/tests/unit/cli/test_cost_estimator.py
index 47d8947b0..973a5f51d 100644
--- a/tests/unit/cli/test_cost_estimator.py
+++ b/tests/unit/cli/test_cost_estimator.py
@@ -79,9 +79,8 @@ class TestBuildGenerationPlan:
def test_empty_repo(self):
builder = _make_graph_builder([])
plans = build_generation_plan([], builder, FakeConfig())
- # Still get repo_overview + architecture_diagram
+ # Still get repo_overview
assert any(p.page_type == "repo_overview" for p in plans)
- assert any(p.page_type == "architecture_diagram" for p in plans)
def test_single_python_file_with_symbol(self):
fi = FakeFileInfo(path="src/app.py", language="python")
diff --git a/tests/unit/cli/test_generate_scope.py b/tests/unit/cli/test_generate_scope.py
index 28913012a..ca8f7ed0c 100644
--- a/tests/unit/cli/test_generate_scope.py
+++ b/tests/unit/cli/test_generate_scope.py
@@ -119,7 +119,6 @@ class _FakeSelection:
self.infra_paths = ["Dockerfile"]
self.symbol_spotlights = [("src/a.py", "Widget")]
self.emit_repo_overview = True
- self.emit_arch_diagram = True
def test_selection_page_ids_mirrors_generation_id_assignment() -> None:
@@ -133,17 +132,14 @@ def test_selection_page_ids_mirrors_generation_id_assignment() -> None:
compute_page_id("infra_page", "Dockerfile"),
compute_page_id("symbol_spotlight", "src/a.py::Widget"),
compute_page_id("repo_overview", "demo"),
- compute_page_id("architecture_diagram", "demo"),
}
def test_selection_page_ids_honors_emit_flags() -> None:
sel = _FakeSelection()
sel.emit_repo_overview = False
- sel.emit_arch_diagram = False
ids = selection_page_ids(sel, "demo")
assert compute_page_id("repo_overview", "demo") not in ids
- assert compute_page_id("architecture_diagram", "demo") not in ids
def test_ranked_ids_to_seed_keeps_unwritten_and_adds_structural() -> None:
diff --git a/tests/unit/generation/test_onboarding.py b/tests/unit/generation/test_onboarding.py
index 3201a4b21..a8e881d52 100644
--- a/tests/unit/generation/test_onboarding.py
+++ b/tests/unit/generation/test_onboarding.py
@@ -174,10 +174,7 @@ def test_target_path_format() -> None:
def test_promoted_slots_map() -> None:
- assert PROMOTED_SLOTS == {
- "repo_overview": "project_overview",
- "architecture_diagram": "architecture_guide",
- }
+ assert PROMOTED_SLOTS == {"repo_overview": "project_overview"}
# ---------------------------------------------------------------------------
@@ -511,7 +508,10 @@ def test_tag_promoted_pages_sets_onboarding_slot() -> None:
]
PageGenerator._tag_promoted_pages(pages)
assert pages[0].metadata["onboarding_slot"] == "project_overview"
- assert pages[1].metadata["onboarding_slot"] == "architecture_guide"
+ # The architecture diagram is no longer a page, so nothing promotes it. A
+ # stale row from an older index must not be tagged into a slot that the
+ # reading order no longer has.
+ assert "onboarding_slot" not in pages[1].metadata
# Non-promoted pages stay untouched.
assert "onboarding_slot" not in pages[2].metadata
diff --git a/tests/unit/generation/test_overview_architecture_map.py b/tests/unit/generation/test_overview_architecture_map.py
new file mode 100644
index 000000000..609ba905b
--- /dev/null
+++ b/tests/unit/generation/test_overview_architecture_map.py
@@ -0,0 +1,101 @@
+"""The architecture map is part of the repository overview.
+
+It used to have a page of its own that described the same repository at the
+same altitude and in the same words as the overview — the two shared roughly a
+quarter of their vocabulary, so a reader who met both read one thing twice.
+The diagram was the only thing that page uniquely had, so it moved here.
+
+The map is the deterministic graph-derived one, not a diagram the model drew,
+and it has to survive every path the overview can be produced by: the model
+path, the deterministic path, and the fallback taken when the provider fails.
+Losing it on the fallback would mean a provider outage silently costs the wiki
+its architecture diagram.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+import pytest
+
+from repowise.core.generation.context_assembler import ContextAssembler
+from repowise.core.generation.models import GeneratedPage
+from repowise.core.generation.page_generator import PageGenerator
+from repowise.core.providers.llm.mock import MockProvider
+
+_MERMAID = "graph TD\n A[cli] --> B[core]\n B --> C[server]"
+
+
+class _OutageProvider(MockProvider):
+ """A provider that fails the way a real outage does: every call raises."""
+
+ async def generate(self, *args, **kwargs):
+ raise RuntimeError("upstream 529 overloaded")
+
+
+@dataclass
+class _Case:
+ name: str
+ gen: PageGenerator
+
+
+def model_gen(sample_config) -> PageGenerator:
+ return PageGenerator(MockProvider(), ContextAssembler(sample_config), sample_config)
+
+
+def outage_gen(sample_config) -> PageGenerator:
+ return PageGenerator(_OutageProvider(), ContextAssembler(sample_config), sample_config)
+
+
+def deterministic_gen(sample_config) -> PageGenerator:
+ cfg = replace(sample_config, deterministic=True)
+ return PageGenerator(MockProvider(), ContextAssembler(cfg), cfg)
+
+
+async def _overview(
+ gen: PageGenerator, sample_repo_structure, mermaid: str | None
+) -> GeneratedPage:
+ return await gen.generate_repo_overview(
+ sample_repo_structure,
+ pagerank={},
+ sccs=[],
+ community={},
+ repo_name="demo",
+ overview_mermaid=mermaid,
+ )
+
+
+async def test_model_written_overview_carries_the_map(model_gen, sample_repo_structure):
+ page = await _overview(model_gen, sample_repo_structure, _MERMAID)
+ assert "## Architecture map" in page.content
+ assert "```mermaid" in page.content
+ assert "A[cli] --> B[core]" in page.content
+
+
+async def test_deterministic_overview_carries_the_map(deterministic_gen, sample_repo_structure):
+ page = await _overview(deterministic_gen, sample_repo_structure, _MERMAID)
+ assert "```mermaid" in page.content
+ assert "A[cli] --> B[core]" in page.content
+
+
+async def test_provider_outage_keeps_the_map(outage_gen, sample_repo_structure):
+ """A provider outage costs the prose around the diagram, never the diagram."""
+ page = await _overview(outage_gen, sample_repo_structure, _MERMAID)
+ assert "```mermaid" in page.content
+ assert "A[cli] --> B[core]" in page.content
+
+
+async def test_embedding_is_idempotent(model_gen, sample_repo_structure):
+ """Reused and cached pages are re-embedded on every run; that must be a no-op."""
+ page = await _overview(model_gen, sample_repo_structure, _MERMAID)
+ assert page.content.count("```mermaid") == 1
+
+
+async def test_no_map_available_leaves_the_page_alone(model_gen, sample_repo_structure):
+ """An empty map must not stamp an empty diagram block onto the page."""
+ page = await _overview(model_gen, sample_repo_structure, "")
+ assert "```mermaid" not in page.content
+ assert page.content.strip()
diff --git a/tests/unit/generation/test_page_redirects.py b/tests/unit/generation/test_page_redirects.py
index 0797b60ff..06096ab6c 100644
--- a/tests/unit/generation/test_page_redirects.py
+++ b/tests/unit/generation/test_page_redirects.py
@@ -176,3 +176,22 @@ class TestShippedTables:
def test_no_retired_type_is_also_a_successor_of_itself(self):
for retired_type, successor in SUPERSEDED_TYPES.items():
assert retired_type != successor
+
+
+# ---------------------------------------------------------------------------
+# The architecture map moved onto the overview
+# ---------------------------------------------------------------------------
+
+
+class TestArchitectureDiagramRetirement:
+ def test_the_retired_page_resolves_to_the_overview(self):
+ assert resolve_superseded("architecture_diagram:repowise") == "repo_overview:repowise"
+
+ def test_it_resolves_for_any_repository(self):
+ """The rule is a type rewrite, so it cannot be repo-specific."""
+ for repo in ("repowise", "some/other-repo", "a"):
+ assert resolve_superseded(f"architecture_diagram:{repo}") == f"repo_overview:{repo}"
+
+ def test_the_overview_itself_is_not_redirected(self):
+ assert resolve_superseded("repo_overview:repowise") is None
+