Website Implementation Plan (Phase G)

A comprehensive, review-ready plan to transform the Portfolio Architecture Portal from a markdown knowledge base into a modern, navigable website — while keeping the markdown as the single source of truth. This document is planning only: no existing files were modified, moved, renamed, or deleted; no code was generated; no content was rewritten. This is the only new file added in Phase G, and it is deliberately not wired into navigation (that is a post-approval step) to honour the “no modifications” constraint.

Guiding principle: the website is a presentation layer over the existing markdown. The markdown in portal/, docs/, ai/, templates/, and the ADRs remains authoritative; the site renders it, never replaces it. This is the portal’s own Principle 2 (definition vs. derivation) applied to itself — content is the definition, the built site is the derivation.

0. Technology validation (Astro stack — confirmed, with one recommendation)

The proposed stack — Astro + Markdown/MDX + Mermaid + Cloudflare Pages + static search + SSG + optional React — is an excellent fit for a markdown-first documentation site. It is affirmed. One material recommendation is added.

Recommendation — evaluate Astro Starlight as the base, not bespoke Astro. Starlight is Astro’s official documentation framework. It provides, out of the box, exactly what this portal needs and would otherwise be hand-built: responsive sidebar navigation, Pagefind search, dark/light mode, accessible components, “edit this page” links, table-of-contents, prev/next, and SEO metadata. It is still Astro — MDX, custom components, and content collections all work.

The rest of this plan is written to work under either A or B; where they differ, both paths are noted.

1. Current State Assessment

Current structure (evidence-based)

• 75 markdown files. portal/ = 52, docs/ = 4, templates/ = 8, ai/ = 3, design/ = 2, showcase/ = 2, skills/ = 2, root = README.md + CLAUDE.md (+ llms.txt).
• portal/ sub-sections: repos/, ventures/, capabilities/, architecture/, operating-model/, governance/, decisions/, current-state/, registry/, plus index.md, portfolio-overview.md.
• All 56 portal/+docs/ pages carry consistent YAML frontmatter (title, type, status, last_reviewed, owner, plus type-specific keys: slug, layer, providers, consumers, adr_number, …).
• 60 Mermaid diagrams across 40 files (mostly graph TD/LR; one quadrantChart in architecture-risks.md).
• llms.txt machine index; internal links are relative markdown paths; 0 broken internal links (verified each phase).
• Conventions: Diátaxis type, <!-- HUMAN -->/<!-- GENERATED --> region markers, kebab-case slugs, zero-padded ADR numbering, templates in templates/.

Strengths

• Exceptional content quality and consistency — uniform frontmatter, templates, cross-linking, Diátaxis typing.
• Rich structured metadata already present (layers, maturity, providers/consumers, ADR status) — directly usable to generate cards, badges, and filters without new content.
• Diagrams are inline Mermaid (text) — versionable, diffable, and renderable to SVG.
• A machine index (llms.txt) and an explicit Information Architecture already define the nav model and routes — the site can derive navigation from these.
• Governance already exists (Documentation Governance) defining source-of-truth per artefact — the site build must respect it.

Weaknesses (for web presentation)

• No description/summary frontmatter field for SEO meta and card subtitles (first paragraph can be used, but an optional field is cleaner).
• No explicit sidebar ordering — order is currently implied by the IA doc, not machine-declared.
• Relative links are markdown-file paths (../repos/x.md) — these must resolve to routes (/repos/x) at build; a link-rewrite step or Astro’s markdown link handling is required.
• Section index pages are README.md — fine, but routing must map portal/x/README.md → /x/.
• design/brand-tokens.md is a placeholder (TBD values) — the design system must be defined (Section 6).
• One newer Mermaid type (quadrantChart) needs a renderer that supports it.

Technical debt (site-relevant, not content defects)

• Manual portal upkeep (already flagged as Risk R8) — the site build should add automated validation (links, frontmatter, Mermaid) to reduce it.
• Two glossaries (docs/glossary.md scoped to portal-maintenance; portal/operating-model/glossary.md authoritative) — the site should present the authoritative one prominently and label the other.

Opportunities

• Turn structured frontmatter into interactive registries (filter/sort capabilities, repos, ADRs).
• Render the layered architecture, dependency map, and reuse map as first-class visual navigation.
• Search across the whole knowledge base (Pagefind) — a major usability gain over browsing GitHub.
• A polished site materially advances the deferred public showcase goal (Phase A/C) — scale & sophistication become visible.

Risks (summarised; full register in Section 10)

• Link/route mismatch during rendering; Mermaid rendering at scale (60 diagrams) and theme-sync; frontmatter gaps for meta; keeping the build in sync with additive content conventions; scope creep into bespoke design.

2. Proposed Architecture

Repository placement (additive, non-disruptive)

The site lives in a new top-level site/ directory; all existing content stays in place. The Astro content layer reads markdown from ../portal, ../docs, ../skills, etc. via glob loaders.

portfolio-portal/               (unchanged root)
├── portal/  docs/  ai/  templates/  skills/  showcase/   ← UNCHANGED source of truth
├── llms.txt  README.md  CLAUDE.md                        ← UNCHANGED
└── site/                        ← NEW, additive (the website project)
    ├── astro.config.mjs
    ├── package.json
    ├── content.config.ts        (glob loaders pointing at ../portal/**, ../docs/**)
    ├── public/                  (favicon, static assets, og images)
    └── src/
        ├── content/             (collection *definitions* only; data loaded from ../portal)
        ├── components/          (cards, badges, diagram, graph — Section 7)
        ├── layouts/             (Base, DocPage, RegistryPage)
        ├── pages/               (route files or Starlight config)
        ├── lib/                 (nav builder, link rewriter, frontmatter helpers)
        └── styles/              (design tokens, theme — Section 6)

Why site/ as a sibling, not a rewrite: it is purely additive (Migration Strategy, Section 4), keeps the knowledge base pristine, and lets the site be deleted/rebuilt without touching content. It mirrors the ecosystem’s own “definition vs derivation” split.

Content structure & routing model

Routing derives from the existing folder structure and the Information Architecture route map — no new IA is invented; the site adopts the documented one.

Astro project layout

• Content collections (Astro 5 Content Layer): one collection per portal section, each a glob() loader over the existing directory, with a Zod schema that mirrors current frontmatter (all fields optional except title) so nothing needs rewriting.
• Dynamic routes: src/pages/[...slug].astro (or Starlight’s auto-routing) maps collection entries to routes.
• Layouts: BaseLayout (head/meta/theme) → DocLayout (sidebar + TOC + content) → specialised RegistryLayout (interactive index pages).

Component hierarchy

graph TD
    Base[BaseLayout<br/>head · theme · skip-link] --> Doc[DocLayout<br/>sidebar · TOC · breadcrumbs · prev/next]
    Base --> Registry[RegistryLayout<br/>filterable grids]
    Doc --> MD[MarkdownContent]
    MD --> Mermaid[ArchitectureDiagram]
    MD --> Callout
    Registry --> CapCard[CapabilityCard]
    Registry --> RepoCard[RepositoryCard]
    Registry --> VenCard[VentureCard]
    Registry --> ADR[ADRSummary]
    CapCard --> Badge[StatusBadge / TechBadge]
    RepoCard --> Badge

Navigation model

• Top nav (header): Overview · Capabilities · Repos · Ventures · Architecture · Operating Model · Governance · Decisions — exactly the documented header nav.
• Left sidebar: section tree derived from folders + an optional sidebar order/group frontmatter key (additive; falls back to alphabetical + README-first).
• Right TOC: generated from page headings (Starlight/rehype autolink).
• Breadcrumbs: mirror the route hierarchy (matches the IA breadcrumb rule).
• In-page cross-links: existing markdown links, rewritten *.md → route.

Search architecture

Pagefind (static, build-time): after Astro builds HTML, Pagefind indexes it and ships a tiny client bundle. Zero infrastructure, works on Cloudflare Pages, respects the “no external service” preference. Search UI is a small island (modal, / to focus). Frontmatter (type, layer, maturity) can be emitted as Pagefind filters for faceted search (e.g. “capabilities that are operational”).

Mermaid rendering strategy

• Primary: client-side, theme-aware rendering via a Mermaid integration (e.g. astro-mermaid or a small rehype step that leaves ```mermaid blocks for a client script). Rationale: 60 diagrams with a hard dark/light requirement — client-side re-renders on theme switch trivially, and supports newer types (quadrantChart).
• Optimization (optional, later): build-time SVG (rehype-mermaid + headless Chromium) for zero-JS, faster first paint, and SSR-safe output — adopt if diagram-heavy pages need it. Note this adds a Playwright build dependency and must be verified against quadrantChart.
• Decision: ship client-side first (fast to build, theme-correct), measure, then selectively pre-render.
• Every diagram gets an accessible caption/aria-label (Section 9) and a horizontal-scroll container so wide graphs never break the layout.

Metadata strategy

• Per-page: title + description (from frontmatter if present, else first paragraph) → <title>, meta description, Open Graph/Twitter cards, canonical URL.
• Structured: type, status, last_reviewed, owner, layer, maturity surfaced as visible page metadata (a “page info” strip) and as Pagefind filters.
• Site-level: sitemap.xml (@astrojs/sitemap), robots.txt, a generated llms.txt parity check (the site can validate its routes against the existing llms.txt).
• OG images: optional generated social cards per page (title + type + layer) — a Phase-4 nicety.

Deployment architecture

graph LR
    DEV[git push to main] --> CF[Cloudflare Pages CI]
    CF --> BUILD[astro build + pagefind index]
    BUILD --> STATIC[Static assets]
    STATIC --> CDN[Cloudflare global CDN]
    PR[Pull request] -.preview deploy.-> PREVIEW[per-PR preview URL]
    CDN --> USER((Visitors))

• Cloudflare Pages, Git-connected: build on push to main; preview deployments per PR (a natural review gate that fits the portal’s governance).
• Static output only (no Workers needed for v1). Custom domain optional. Build command npm run build (runs astro build then pagefind), output dir site/dist.

3. Content Strategy

Files stay where they are. The Astro content layer loads them in place via glob loaders — no content moves, renames, or rewrites. This is the single most important content decision and it is fully supported by Astro 5.

Frontmatter

• No rewrite required. The collection schema mirrors existing fields; everything except title is optional.
• Recommended additive (optional) fields, applied lazily/only where useful, never in bulk:
  • description — one-line summary for meta + card subtitle (else derived from first paragraph).
  • sidebar — { order, group, label } for deterministic nav (else folder + README-first + alphabetical).
  • hidden: true — exclude a page (e.g. templates) from the public site if desired.
• Adding these is purely additive and can be done page-by-page over time; the site works without them.

Related pages

Generated from existing signals, not new content:

• Same-section siblings (folder).
• Frontmatter relationships (providers, consumers, layer, system) → “related repos/capabilities”.
• Outbound markdown links already present in each page.
• ADRs referenced by a page ↔ pages referenced by an ADR (bidirectional, from link graph).

Navigation generation

Derived from (a) folder structure, (b) the Information Architecture route/nav tables, and © optional sidebar frontmatter. No hand-maintained nav file that can drift.

Search indexing

Pagefind indexes the built HTML (post-build). Frontmatter type/layer/maturity emitted as filters. templates/ and any hidden pages excluded from the index.

Diagram rendering

```mermaid fenced blocks are detected and rendered (client-side, theme-aware) — the existing blocks are used as-is. No diagram content is rewritten. Wide diagrams scroll within their container.

Link rewriting (the one build-time transform)

A small rehype/remark step rewrites internal *.md links to routes (../repos/x.md#sec → /repos/x#sec) at build time. Source markdown is untouched on disk; the transform happens in the render pipeline only.

4. Migration Strategy

Every proposed change is additive; the knowledge base is not restructured. Ordered by necessity.

Disruption assessment: M1–M3, M6–M7 touch only the new site/ dir and (M7) the existing .gitignore (a one-line additive edit at implementation time, not now). M4–M5 are optional and incremental. No content file is moved, renamed, or rewritten.

5. User Experience

Homepage (/)

A confident landing that answers “what is this ecosystem?” in 10 seconds, then routes deeper. Sections: hero (the vision one-liner), the layered architecture diagram (interactive), quick-links to the two primary registries (Capabilities, Repos), current phase/status, and “start here” cards (Overview, Operating Model, Governance). Sourced from portfolio-overview.md + index.md — no new copy invented.

Navigation

Persistent header (primary sections) + collapsible left sidebar (section tree) + right TOC + breadcrumbs + search (/). Mobile: header collapses to a menu; sidebar becomes a drawer.

Page types & their experience

How users move through the site

graph LR
    HOME[Home] --> OV[Overview]
    HOME --> SEARCH[Search]
    OV --> CAP[Capability Registry] --> CAPX[Capability page] --> REPO[Repo page]
    OV --> ARCH[Architecture] --> DIAG[Dependency map] --> REPO
    REPO --> ADR[Related ADRs]
    ANY[Any page] --> GLOSS[Glossary term]
    ANY --> SEARCH

Three entry patterns: browse (nav/sidebar), search (Pagefind, faceted), and follow relationships (cards, related links, diagram nodes → pages).

6. Design System

Fill the existing design/brand-tokens.md placeholder and encode tokens in site/src/styles. The visual language is technical, editorial, and calm — content-first, high signal-to-noise.

Reference characteristics (adopted, not copied)

• Stripe — restrained colour, confident typographic hierarchy, generous whitespace, crisp tables.
• Vercel — high-contrast minimalism, excellent dark mode, tight card grids.
• Cloudflare Docs — dense-but-navigable docs IA, strong sidebar/TOC, code/diagram legibility.
• Microsoft Learn — structured metadata strips, progressive disclosure, accessible components. We adopt: typographic hierarchy, whitespace discipline, dark-mode-first contrast, metadata strips, and diagram legibility — not any specific implementation or brand look.

Typography

• A clean humanist sans for UI/headings (e.g. Inter/IBM Plex Sans class) and a legible body face; a mono for code/IDs/slugs. Self-hosted (no external font fetch, aligns with static/privacy goals).
• Modular scale (~1.2), long-form measure ≤ 72ch, clear H1–H4 rhythm.

Colour strategy

• Neutral-dominant palette with one brand accent + semantic status colours mapped to the portal’s own vocabulary: ✅ operational (green), 🔶 partial/early (amber), ⏳ planned (grey-blue), ❌/risk (red), proposed (violet). These already exist as emoji markers in content — the design formalises them.
• WCAG-checked (see Section 9); accent used sparingly for links/CTAs/active-nav.

Spacing, cards, navigation, responsiveness

• 4/8px spacing scale; generous section spacing; sticky header + sidebar.
• Cards are the core unit (capability/repo/venture/ADR) — consistent padding, badge row, title, one-line summary, footer links.
• Responsive breakpoints: sidebar drawer < 1024px; single-column < 768px; tables/diagrams scroll horizontally in their own container (never break the page).

Diagrams

• Mermaid theme variables bound to design tokens, with two variants (light/dark) that switch with the site theme; captions + accessible descriptions; max-width with horizontal scroll.

Dark/light mode

• Dark-mode-first, both fully supported; respect prefers-color-scheme; a toggle persists choice; Mermaid re-renders on switch. (Starlight provides this; bespoke Astro must implement it.)

Accessibility (design-level)

• AA contrast for body & UI; visible focus rings; skip-to-content; semantic landmarks; reduced-motion honoured. Full validation in Section 9.

7. Components

Components are presentation-only and derive from existing frontmatter/content — none require new content. Most are static; only RelationshipGraph and SearchModal are interactive islands (React/Preact or vanilla), used because they are genuinely better interactive.

8. Implementation Roadmap

Incremental; the site is deployable and useful from Phase 1 onward.

Sequencing rule: the site stays functional after each phase (G1 already renders everything; later phases enhance). Effort is indicative for a single implementer; each phase ends with a review gate per the portal’s own Architecture Review Lifecycle.

9. Validation Strategy

10. Risks and Recommendations

Top recommendations

1. Adopt Astro Starlight as the base (fastest path to nav/search/theming/a11y); keep bespoke Astro as the fallback.
2. Keep all content in place; load via Astro 5 glob loaders — the plan’s cornerstone.
3. Client-side, theme-aware Mermaid first; optimise later.
4. Isolate everything in site/; the only pre-implementation edit ever needed is one additive .gitignore line (deferred to implementation).
5. Add CI validation (links/frontmatter/Mermaid/a11y) to convert manual upkeep (R8) into automated guardrails.
6. Formalise the design tokens into the placeholder design/brand-tokens.md as the first design act.

Alignment with existing portal work (built upon, not duplicated)

This plan consumes — and does not replace — the Repository Registry, Capability Registry, Portfolio Overview, Architecture Principles, Operating Model, Governance, the ADRs, Architecture Review, Capability Reuse Map, System Dependency Maps, the Information Architecture, and all 60 Mermaid diagrams. The website renders this knowledge; the markdown remains authoritative.

Post-approval next steps (NOT done in Phase G)

On approval: record an ADR (e.g. “Adopt Astro/Starlight website as the portal presentation layer”), add the site/ project (Roadmap G1), and wire a “Website” entry into navigation and the changelog. None of these were performed in this planning phase.

Phase G deliverable — planning only. One new file added (docs/website-implementation-plan.md); no existing file modified, moved, renamed, or deleted; no code generated; no content rewritten.