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

ADR 0001: Record architecture decisions & adopt the markdown-first portal

  • Status: accepted
  • Date: 2026-07-05
  • Deciders: Azwaan
  • Tags: structure, tooling, cross-repo

Context

Azwaan operates a growing ecosystem of AI ventures and repositories. Repo-level docs explain each repo in isolation, but nothing explains the system of systems — how repos and ventures combine — or communicates the ecosystem’s scale to an external audience. Decisions about that structure need a durable, reviewable record from day one.

Decision

We will:

  1. Maintain a dedicated markdown-first Portfolio Architecture Portal as the system-of-systems layer, structured per the three-layer design principle (repo docs → portal → public showcase).
  2. Record significant structural and cross-repo decisions as ADRs in portal/decisions/, using the Michael Nygard ADR style captured in the ADR template.
  3. Drive all content through canonical templates and a Diátaxis documentation model, so the portal is consistent and later machine-maintainable by the portfolio-portal-orchestrator skill.

Options considered

Option Pros Cons
A (chosen): markdown-first portal + ADRs Renders on GitHub; diffable; automation-friendly; low overhead Manual upkeep until automation exists
B: Build the public website first Immediate showcase Premature; no stable content model; hard to maintain
C: Keep only per-repo docs No new repo to maintain No system-of-systems view; no showcase path

Consequences

  • Positive: A single source of truth for the ecosystem map; a clean target for future automation; ADRs give decision provenance.
  • Negative / trade-offs: Requires discipline to keep digests, registry, and diagrams in sync until the orchestrator is built.
  • Follow-ups / affected pages: All Phase A scaffolding (this initialization); future ADRs will cover naming conventions, venture boundaries, and the orchestrator’s generated-region contract.

Compliance / review

Adherence is checked via the Definition of Done in CLAUDE.md and the invariants in update conventions. Revisit if the portal outgrows a markdown-first model.