Portfolio Portal
ADR accepted owner: Azwaan reviewed: 2026-07-05

ADR 0007: Portfolio Graph as the canonical runtime model; custom Astro website

  • Status: accepted
  • Date: 2026-07-05
  • Deciders: Azwaan
  • Tags: implementation, website, portfolio-graph

Records the Phase G1 implementation decisions. Builds on the approved website implementation plan and its strategy validation.

Context

Phase G1 began implementation: turn the markdown knowledge base into a navigable platform without making the website a second source of truth. The strategy validation established that the portal is an architecture platform (explorer, showcase, working environment), not a documentation site, and recommended a build-time content graph as the backbone for the site and all future Portfolio Intelligence.

Decision

  1. Introduce the Portfolio Graph — a build-time, typed graph (nodes + typed edges + stats) generated from the markdown by a zero-dependency Node script (site/scripts/build-graph.mjs; schema in site/GRAPH-SCHEMA.md). The data flow is strictly Markdown → Portfolio Graph → Website → (future) Intelligence/APIs/Automation. The website consumes the graph, never the markdown filesystem directly. The graph is exposed at GET /api/graph.json.
  2. Build the website in custom Astro (not Starlight) — per the validated objectives; Astro’s primitives (content, Pagefind-class search, MDX, islands) are kept while its layout ceiling is removed.
  3. Entity-aware search over the graph — a graph-derived search index that understands entities (repository, capability, venture, technology, principle, ADR, glossary term), refining Phase G’s Pagefind default to match the “search understands entities” requirement.
  4. Additive only — the site lives in site/; all markdown stays in place; nothing was moved, renamed, or rewritten. Generated graph artefacts are git-ignored (derived, never a source of truth).

Options considered

Option Pros Cons
A (chosen): Portfolio Graph + custom Astro One canonical model for all consumers; platform-grade flexibility; intelligence-ready Rebuild doc chrome; a build step
B: Astro Starlight reading files Fast chrome Website couples to files; constrains explorer/dashboards; two-source-of-truth risk
C: Render markdown directly in the site, no graph Simplest No relationship model; no path to search-as-entities or Portfolio Intelligence

Consequences

  • Positive: relationship-aware navigation, entity search, and a stable /api/graph.json contract fall out of one model; future intelligence (drift, staleness, health, Hermes) consumes the same graph without refactoring; markdown remains authoritative.
  • Negative / trade-offs: a build-time generation step; doc chrome is hand-built; the graph must stay in sync with content conventions (mitigated: it derives purely from frontmatter + links + diagram node IDs).
  • Follow-ups: later phases add the global /explore graph, clickable diagram nodes, filterable registries, dashboards, and the additive intelligence metadata (id, implementation_status, confidence, review_frequency, related, source_repos).

Compliance / review

The invariant — no architectural knowledge exists only in the website; everything originates in the markdown and the generated graph — is enforced by the data flow and reviewed at each phase gate.