feat: explain configured institutional architecture

src/govoplan_docs/backend/api/v1/routes.py

@@ -20,6 +20,10 @@ from govoplan_core.core.modules import (
     user_workflow_scope_condition_issues,
 )
 from govoplan_core.core.registry import PlatformRegistry
+from govoplan_core.core.provider_governance import (
+    ExternalProviderStateContext,
+    collect_external_provider_states,
+)
 from govoplan_core.core.versioning import (
     format_version_range,
     version_satisfies_range,
@@ -57,6 +61,7 @@ def docs_context(
             detail="Administrative documentation requires documentation-administrator authority",
         )
     registry = _registry(request)
+    external_provider_states = _external_provider_states(registry, principal)
     target_version = version if isinstance(version, str) else None
     resolved_locale = _preferred_locale(request, locale)
     route_items = _route_items(registry.manifests(), principal)
@@ -84,12 +89,14 @@ def docs_context(
         catalog = _admin_documentation_catalog(
             registry,
             principal,
+            external_provider_states=external_provider_states,
             route_items=route_items,
             visible_route_items=visible_route_items,
         )
     else:
         catalog = _user_documentation_catalog(
             registry,
+            external_provider_states=external_provider_states,
             visible_route_items=visible_route_items,
             documentation_layers=documentation_layers,
         )
@@ -193,12 +200,17 @@ def _admin_documentation_catalog(
     registry: PlatformRegistry,
     principal: ApiPrincipal,
     *,
+    external_provider_states: Mapping[str, Mapping[str, object]],
     route_items: list[dict[str, Any]],
     visible_route_items: list[dict[str, Any]],
 ) -> dict[str, list[dict[str, Any]]]:
     return {
         "modules": [
-            _module_payload(manifest, technical=True)
+            _module_payload(
+                manifest,
+                technical=True,
+                external_provider_states=external_provider_states,
+            )
             for manifest in registry.manifests()
         ],
         "permissions": [
@@ -214,6 +226,7 @@ def _admin_documentation_catalog(
 def _user_documentation_catalog(
     registry: PlatformRegistry,
     *,
+    external_provider_states: Mapping[str, Mapping[str, object]],
     visible_route_items: list[dict[str, Any]],
     documentation_layers: Mapping[str, list[dict[str, Any]]],
 ) -> dict[str, list[dict[str, Any]]]:
@@ -226,7 +239,11 @@ def _user_documentation_catalog(
     }
     return {
         "modules": [
-            _module_payload(manifest, technical=False)
+            _module_payload(
+                manifest,
+                technical=False,
+                external_provider_states=external_provider_states,
+            )
             for manifest in registry.manifests()
             if manifest.id in visible_module_ids
         ],
@@ -314,6 +331,13 @@ def _documentation_summary(
     permissions = catalog["permissions"]
     return {
         "module_count": len(catalog["modules"]),
+        "architecture_declared_module_count": sum(
+            1 for item in catalog["modules"] if item.get("architecture")
+        ),
+        "external_provider_count": sum(
+            int(item.get("external_provider_count") or 0)
+            for item in catalog["modules"]
+        ),
         "visible_route_count": len(catalog["visible_routes"]),
         "available_route_count": len(catalog["available_routes"]),
         "permission_count": len(permissions),
@@ -371,9 +395,34 @@ def _registry(request: Request) -> PlatformRegistry:
     return registry
 
 
-def _module_payload(manifest: ModuleManifest, *, technical: bool) -> dict[str, Any]:
+def _module_payload(
+    manifest: ModuleManifest,
+    *,
+    technical: bool,
+    external_provider_states: Mapping[str, Mapping[str, object]] | None = None,
+) -> dict[str, Any]:
     frontend = manifest.frontend
     migration = manifest.migration_spec
+    architecture = manifest.architecture.to_dict() if manifest.architecture else None
+    if architecture is not None and not technical:
+        architecture = {
+            "contract_version": architecture["contract_version"],
+            "layer": architecture["layer"],
+            "kind": architecture["kind"],
+            "maturity": architecture["maturity"],
+            "known_limits": architecture["known_limits"],
+            "supported_authority_modes": architecture[
+                "supported_authority_modes"
+            ],
+            "owned_concepts": architecture["owned_concepts"],
+            "non_owned_concepts": architecture["non_owned_concepts"],
+            "reference_packages": architecture["reference_packages"],
+            "target_tested_providers": architecture[
+                "target_tested_providers"
+            ],
+            "evidence": [],
+            "documentation": {},
+        }
     return {
         "id": manifest.id,
         "name": manifest.name,
@@ -390,9 +439,87 @@ def _module_payload(manifest: ModuleManifest, *, technical: bool) -> dict[str, A
         "capabilities": sorted(manifest.capability_factories) if technical else [],
         "documentation_count": len(manifest.documentation) if technical else 0,
         "documentation_provider_count": len(manifest.documentation_providers) if technical else 0,
+        "architecture": architecture,
+        "external_provider_count": len(manifest.external_providers),
+        "external_providers": [
+            {
+                **(
+                    declaration.to_dict()
+                    if technical
+                    else {
+                    "id": declaration.id,
+                    "module_id": declaration.module_id,
+                    "label": declaration.label,
+                    "maturity": declaration.maturity,
+                    "operations": list(declaration.operations),
+                    "authority_modes": list(declaration.authority_modes),
+                    "known_outage_behavior": declaration.behavior.outage,
+                    }
+                ),
+                "runtime_state": _documentation_provider_state(
+                    (external_provider_states or {}).get(declaration.id),
+                    technical=technical,
+                ),
+            }
+            for declaration in manifest.external_providers
+        ],
     }
 
 
+def _documentation_provider_state(
+    state: Mapping[str, object] | None,
+    *,
+    technical: bool,
+) -> dict[str, object] | None:
+    if state is None:
+        return None
+    if technical:
+        return dict(state)
+    return {
+        key: state.get(key)
+        for key in (
+            "configured",
+            "active",
+            "authority_mode",
+            "authority_modes",
+            "health",
+            "freshness",
+            "conflict",
+            "recovery",
+            "observed_at",
+        )
+    }
+
+
+def _external_provider_states(
+    registry: PlatformRegistry,
+    principal: ApiPrincipal,
+) -> dict[str, dict[str, object]]:
+    registrations = registry.external_provider_state_providers()
+    if not registrations:
+        return {}
+    tenant_id = str(principal.tenant_id or "").strip() or None
+    try:
+        with get_database().session() as session:
+            return collect_external_provider_states(
+                registrations,
+                ExternalProviderStateContext(
+                    session=session,
+                    tenant_id=tenant_id,
+                    principal=principal,
+                ),
+            )
+    except Exception:  # noqa: BLE001 - return sanitized per-provider diagnostics.
+        return collect_external_provider_states(
+            registrations,
+            ExternalProviderStateContext(
+                session=None,
+                tenant_id=tenant_id,
+                principal=principal,
+            ),
+        )
+
+
 def _user_route_payload(item: Mapping[str, Any]) -> dict[str, Any]:
     return {
         "module_id": item["module_id"],