Website Strategy Validation (Phase G.5)

A final architectural review of the website strategy before implementation, evaluated against the portal’s actual purpose — an architecture exploration tool, EA knowledge base, operating manual, portfolio showcase, and daily architecture-working environment — not a conventional documentation site. This is planning only: no code, no Astro project, no file moves, no modification of existing documentation. It is one new additive file that refines the Website Implementation Plan by reference — the plan is not edited; this document states what is approved, refined, or newly recommended.

Every recommendation is tagged: ✅ APPROVED (keep as planned) · 🔧 REFINED (change, with reason) · 🟢 OPTIONAL-FUTURE (design-ready, build later).

Headline outcome: the clarified objective changes one major decision — the technology base — and adds a build-time content graph as the architectural backbone for exploration and future Portfolio Intelligence. Most of the Phase-G plan stands. Nothing is changed for the sake of change.

Part 1 — Technology recommendation (re-evaluated)

Phase G recommended Astro Starlight, optimising for a documentation site. The objective is now explicitly a platform: exploration, interactive visualisation, premium presentation, dashboards, and future intelligence. That reframing changes the recommendation.

Evaluation against the real objectives

Starlight wins maintainability and time-to-first-deploy (both one-time/near-term). Custom Astro wins on almost every dimension tied to the portal’s long-term purpose.

The maintainability counter-argument, mitigated

Starlight’s real value is the free doc chrome. In custom Astro it is recoverable with modest, well-supported effort:

Net: custom Astro recovers ~80% of Starlight’s chrome in a few days — a one-time cost — in exchange for the freedom the platform objectives require permanently.

Other alternatives (screened)

• Next.js / React SPA: heavier, SSR/client-oriented; overkill for a mostly-static knowledge base; worse markdown ergonomics than Astro. ❌
• VitePress / Docusaurus: more doc-locked than Starlight; framework-coupled (Vue/React); less island flexibility. ❌
• Notion/Obsidian-publish/GitBook (hosted): would make a hosted tool the source of truth, violating “markdown = source of truth” and Cloudflare-static goals. ❌

Final recommendation — 🔧 REFINED: Custom Astro (reversing the Starlight default)

Build on custom Astro (content collections + Pagefind + MDX + Mermaid + React islands + Cloudflare Pages). Astro remains correct — it is the Starlight base recommendation that changes. Reasoning: the portal’s centre of gravity is exploration, showcase, and a working environment, not long-form reading; Starlight optimises the subset (doc pages) and constrains the differentiators (explorer, platform homepage, dashboards, premium identity, intelligence UI). Astro keeps all of Starlight’s underlying primitives while removing its layout ceiling.

Adopt from the Starlight approach anyway: Pagefind search, content-collection modelling, and Starlight’s open-source components as reference patterns for the doc-chrome we rebuild. If time-to-first-deploy ever becomes paramount, a Starlight MVP is a valid stepping stone — but since intent is known, building custom now avoids a later rewrite.

Everything else in the Phase-G plan (glob loaders, files-stay-in-place, Pagefind, client-side theme-aware Mermaid, Cloudflare Pages, site/ isolation, additive migration) remains ✅ APPROVED and is more natural under custom Astro than under Starlight.

Part 2 — User Journeys

Design for audiences and their journeys, then validate nav/homepage against them.

Primary audiences & journeys

What the journeys imply (validation)

1. Two dominant modes: explore relationships (you, architects, AI engineers) and assess quickly then drill (employers, investors, clients). The homepage and nav must serve both — an explorer for the first, scale + curated deep-links for the second.
2. Search is a primary entry for engineers — must be excellent and faceted.
3. Audience-aware entry on the homepage (“I’m an architect / engineer / investor …”) materially shortens paths — 🔧 REFINED into the homepage (Part 5).
4. Honesty is a feature for investors/employers — the maturity/▢-labelling already in content is a credibility asset; surface it, don’t hide it.

Part 3 — Interactive Architecture Explorer

The portal should let users move through relationships, not just read linked pages.

The relationship model (derived from existing metadata — no new content)

The chain the brief describes already exists implicitly in frontmatter + links:

Capability ─ owns/consumed-by ─ Repositories ─ uses ─ Technologies
    │                               │
    ├─ serves ─ Ventures            ├─ decided-by ─ ADRs
    ├─ governed-by ─ Principles     └─ documented-in ─ Diagrams
    └─ realised-in ─ Operating Model / Knowledge Assets

Edges come from: providers/consumers/layer/system frontmatter, the markdown link graph, and diagram node IDs (which were deliberately kept equal to slugs — a key enabler).

How it should work (two complementary mechanisms)

A. Per-entity “relationship rails” (🔧 REFINED, primary). Every page gains a structured side/end panel of typed related entities (Capabilities ▸ Repos ▸ Technologies ▸ Consumers ▸ Ventures ▸ Principles ▸ ADRs ▸ Diagrams). Intuitive, low-risk, works without heavy graph UI, and is generated from the content graph (Part 8).

B. A global interactive graph — the “Explorer” (🟢 OPTIONAL-FUTURE, high value). A dedicated /explore route with a node-link graph:

• Focus mode: click a node → recenter on it → show its immediate neighbourhood (avoids hairball).
• Filter by layer / maturity / type.
• Nodes link to their pages; edges are typed and labelled.
• Fed by the same build-time JSON graph; rendered by a lightweight island.

graph LR
    HOME[Home] --> EXP["/explore — global graph"]
    EXP -->|focus node| NODE[Entity neighbourhood]
    NODE --> PAGE[Entity page]
    PAGE --> RAILS[Relationship rails]
    RAILS --> PAGE2[Another entity]
    ANY[Any page] --> RAILS

Visualisation recommendations (avoid over-engineering)

• Do: reuse existing Mermaid diagrams as interactive navigation (Part 6); build relationship rails from the content graph; add one focused /explore graph with focus+filter.
• Don’t: introduce a graph database, a 3D graph, or a bespoke query language. Derive edges at build time; keep the client light. Intuitive beats impressive.

Part 4 — Information Architecture review

Challenging the current nav (Overview · Capabilities · Repos · Ventures · Architecture · Operating Model · Governance · Decisions + About).

Findings

Recommended top-level nav (🔧 REFINED — materially simpler, purpose-first)

Explore · Overview · Capabilities · Repositories · Architecture · Operating & Governance · Decisions

• Explore → the graph + relationship-first entry (new front door for the platform purpose).
• Operating & Governance merges the two meta-sections under one bucket (each keeps its landing page and sub-nav) — reduces header load without losing content.
• Ventures & Systems moves under Architecture/Explore until populated (data unchanged).

This is a navigation refinement only — no content moves or renames; it changes how the site groups existing pages. The Information Architecture doc’s routes are preserved.

Part 5 — Homepage review

The Phase-G homepage (hero + layered diagram + registry links + status + start-here) is solid but reads a bit documentation-like. Against the “entering a sophisticated AI platform” bar:

Refined homepage (🔧 REFINED)

1. Hero = the interactive layered architecture (clickable, theme-aware), with the vision sentence.
2. Scale strip (computed metrics) — instant “this is substantial”.
3. Audience chips — route by intent.
4. The two registries (Capabilities, Repositories) as prominent cards.
5. Current phase / health (from current-state) — signals it’s alive and maintained.
6. Entry to /explore — the platform’s defining action.

The test: within 10 seconds a visitor should grasp what it is, how big it is, how it fits, and feel invited to explore — not to read a manual. Motion/depth should be restrained and purposeful (premium, not flashy).

Part 6 — Visual exploration (diagrams as primary navigation)

Today diagrams illustrate content. They should drive navigation. The decisive enabler already exists: Mermaid node IDs were kept equal to entity slugs across the portal, so nodes can map to routes mechanically.

Recommendations

Implementation note (design-level): add a build/render step that turns Mermaid nodes into links where a node ID matches a known slug (Mermaid supports click bindings / post-render link injection). Diagrams that are just narrative stay static. This is low effort, high payoff precisely because of the earlier slug-discipline.

🔧 REFINED: treat “interactive diagrams” as a first-class site feature, not a nice-to-have; 🟢 OPTIONAL-FUTURE: the full /explore graph.

Part 7 — Metadata recommendations

Current frontmatter (title · type · status · last_reviewed · owner + type-specific slug · layer · providers · consumers · maturity · lifecycle · adr_number) is strong. Recommended additive fields — only those with clear long-term value for automation & intelligence (Part 8). All optional; no existing content rewritten.

Guidance: introduce these lazily (page-by-page, highest-value pages first), keep schema all-optional, and let the site derive fallbacks. Encode them in the templates so new pages get them for free. last_reviewed + review_frequency + implementation_status + confidence are the four that unlock Portfolio Intelligence.

Part 8 — Portfolio Intelligence readiness

Ensure the website architecture is ready for future intelligence — design now, build later — to avoid expensive refactoring.

The one thing to design now: a build-time Content Graph

A JSON model of the whole portal, produced at build from frontmatter + links + diagram nodes:

graph LR
    MD[Markdown + frontmatter] --> BUILD[Build step]
    LINKS[Link graph] --> BUILD
    DIAG[Mermaid node IDs] --> BUILD
    BUILD --> GRAPH[(content-graph.json<br/>entities + typed edges + metadata)]
    GRAPH --> SITE[Site: rails · explorer · scale strip]
    GRAPH --> ENDPOINT[Static JSON endpoints]
    ENDPOINT --> FUTURE[Future: dashboards · drift · health · AI · Hermes]

The content graph is the single backbone the site and every future intelligence feature consume. Design it now; it costs little and prevents a later rewrite.

Readiness per future capability

Design-now checklist (no implementation)

• [ ] Content graph as a build artefact + static JSON endpoints (Astro supports both).
• [ ] Additive metadata (Part 7): id, implementation_status, confidence, review_frequency, related, source_repos.
• [ ] Preserve <!-- GENERATED -->/<!-- HUMAN --> regions so the orchestrator can write safely.
• [ ] Keep node ID = slug discipline (already in place) so diagrams join the graph.
• [ ] A per-entity health schema computable from metadata (staleness, gaps, drift) — design the schema, don’t build the checks.
• [ ] The site consumes the graph via components so intelligence features reuse the same data path.

This directly serves — and does not pre-empt — the existing portfolio-portal-orchestrator spec and the operating model’s future-autonomy vision.

Summary of decisions

✅ Approved (Phase-G plan stands)

Files stay in place (glob loaders) · Pagefind static search · client-side theme-aware Mermaid · Cloudflare Pages · site/ isolation · additive migration · content strategy · validation strategy · roadmap shape · description/sidebar frontmatter.

🔧 Refined (change, with reason)

1. Custom Astro instead of Starlight (objectives = platform, not docs).
2. “Explore” as a primary nav entry; simpler top-nav buckets; standardise labels; fold thin sections.
3. Homepage = interactive layered hero + scale strip + audience chips + explore CTA (platform feel).
4. Diagrams as primary navigation (clickable nodes → routes, via the slug discipline).
5. Relationship rails on every entity page.
6. Additive intelligence metadata (id, implementation_status, confidence, review_frequency, related, source_repos).

🟢 Optional-future (design-ready, build later)

Global /explore graph with focus+filter · content-graph JSON endpoints · dashboards · drift/health/stale detection · venture-scoped views · generated OG images.

Roadmap impact (refines Phase G’s G1–G6, does not replace it)

• G1 now stands up custom Astro (not Starlight) + rebuild minimal chrome; add the content-graph build artefact early (it underpins G2/G3/G5).
• G3 interactive Mermaid (node→route) is promoted from nice-to-have to core.
• G5 registries + relationship rails + optional /explore.
• Metadata (Part 7) is applied lazily across all phases via templates.

Phase G.5 deliverable — validation & refinement only. One new file added (docs/website-strategy-validation.md); no code, no Astro project, no file moves/renames, no existing documentation modified.