Product And Architecture Review designed

Use this page to review the documentation portal shape with Product and Architecture. The goal is to confirm that the portal has the right audience paths, source-of-truth model, and review gates before expanding it into a broader internal or external documentation surface.

This is not an approval to publish externally yet. It is a review of whether the portal is structured correctly enough to keep building.

Review Scope

Area	Review focus	What good looks like
Information architecture	Audience paths, page families, navigation, and reading order	A product, architecture, developer, security, or operator reader can find their path without knowing the repo layout
Product framing	Persona separation, user/admin/developer/operator language, and public-facing readiness	Product pages explain what the platform does without leaking internal implementation detail
Architecture framing	Platform foundation, shared services, route/domain ownership, source docs, and boundary rules	Architecture pages summarize durable decisions while canonical specs remain under doc/**
Developer path	App SDK, API contracts, auth/access, idempotency, and generated reference plan	Developers can see the intended path even before published SDK artifacts and generated API docs are complete
External readiness	Public, customer, partner, and internal publication tracks	Visibility metadata and readiness checks exist before any external publication work starts
Visual standards	Mermaid, maintained image assets, and diagram source ownership	Diagrams improve understanding without becoming unowned screenshots or stale copies

Reading Path

1. Start Here
2. Portal Roadmap
3. Product
4. Architecture
5. Build on AI Cloud
6. Developer APIs
7. Product External Viewer Path
8. Architecture External Viewer Path
9. External Publication Readiness
10. Source Of Truth Model
11. Visual Standards

Product Review Questions

Question	Decision needed
Are the audience paths correct for product, users, tenant admins, developers, operators, security, and architects?	Approve the first portal IA or identify missing page families
Should Build on AI Cloud remain a top-level path?	Confirm App SDK and app developer onboarding priority
Is the product language clear enough for internal stakeholders who do not know the implementation?	Identify terms that need product naming or glossary work
Which pages should become public, customer-only, partner-only, or internal first?	Prioritize the first publication track
Are product journeys and v3 IA represented accurately without becoming a second source of truth?	Confirm the portal summary pattern

Architecture Review Questions

Question	Decision needed
Does the portal preserve canonical authority under doc/** while making the content readable?	Approve the source-of-truth model
Does the architecture path explain platform foundation, shared services, and domain ownership accurately?	Identify missing architecture pages or incorrect summaries
Is the sequence visible enough: maps first, guard visibility second, facade implementation third?	Confirm the implementation discipline for platform foundation work
Do API, event, deployment, and code-boundary pages avoid drifting ahead of approved architecture docs?	Confirm what must remain generated or source-linked
Are open decisions visible enough for teams picking up implementation work?	Decide whether to add a dedicated open-decisions portal page

Decisions To Capture

Decision	Owner	Outcome
First-review IA acceptance	Product + Architecture	Approve as-is, approve with changes, or request another review pass
Publication track ordering	Product + Security + Architecture	Choose public, customer, partner, or internal-first track sequence
Generated API reference priority	Architecture + Developer Experience	Decide when OpenAPI and AsyncAPI rendering becomes a blocking portal task
Diagram backlog	Product + Architecture	Pick the first maintained image assets that Mermaid cannot express well
App SDK portal readiness	Product + App Platform	Decide what is needed before internal developers can use the SDK path
Open decision visibility	Architecture	Decide whether open decisions stay in source docs only or get a portal summary

Known Non-Goals

• The portal does not replace canonical doc/** source documents.
• This review does not publish the portal externally.
• This review does not implement access control.
• This review does not complete generated OpenAPI or AsyncAPI reference rendering.
• This review does not freeze all portal wording; it validates structure and reviewability.

Evidence To Check

Evidence	Expected result
make docs-portal-check	Source-doc guard and Docusaurus build pass
Fairway readiness report	Docusaurus portal gates are satisfied for the current task set
source_docs metadata	Every review page points back to canonical source docs
Publication track metadata	Pages declare visibility and status before external publication

Feedback Format

For each issue, capture:

1. Portal path or section.
2. Audience affected.
3. Problem or ambiguity.
4. Requested change.
5. Canonical source doc owner, if known.

Canonical sources

• doc/PORTAL_SYNC.mdraw
• doc/product/GPUaaS_Documentation_and_Developer_Portal_Docusaurus_v1.mdraw
• doc/product/Product_Surface_IA_and_Role_Model_v1.mdraw
• doc/architecture/platform-foundation/Platform_Shared_Services_Model_v2.mdraw
• doc/architecture/API_Domain_Authoring_Model_v1.mdraw
• doc/architecture/API_Route_Modularization_and_V1_Freeze_v1.mdraw
• doc/architecture/Platform_Architecture_Open_Decisions_v1.mdraw