Portfolio Portal

Portfolio Architecture Portal

A markdown-first architecture and showcase portal for Azwaan’s AI venture ecosystem.

This repository is the single source of truth that explains the system of systems — how individual repositories, ventures, and services fit together — and, eventually, feeds a public showcase that communicates the scale and sophistication of the ecosystem.

The three layers

This portal deliberately separates three levels of explanation:

Layer Question it answers Where it lives
Repo-level docs What is this individual repo and how does it work? Inside each repo (README, docs, ADRs, CLAUDE.md)
Portfolio portal (this repo) How do the repos, ventures, and services combine into a system of systems? portal/
Public showcase How large and sophisticated is the venture ecosystem? showcase/ — later target, not built yet

Design principle Repo-level docs explain individual repos. The portfolio portal explains the system of systems. The public showcase explains the scale and sophistication of Azwaan’s AI venture ecosystem.

Repository map

portfolio-portal/
├── README.md                     # You are here
├── CLAUDE.md                     # How this repo is maintained (read before editing)
├── llms.txt                      # Machine-readable index of the portal
├── docs/                         # How the portal itself is structured & maintained
│   ├── information-architecture.md   # Page hierarchy + navigation model
│   ├── documentation-model.md        # Diátaxis model for portal content
│   ├── update-conventions.md         # When & how to update each page
│   └── glossary.md                   # Shared vocabulary
├── portal/                       # THE SYSTEM-OF-SYSTEMS LAYER
│   ├── index.md                      # Portal home / entry point
│   ├── portfolio-overview.md         # Executive briefing (read first)
│   ├── capabilities/                 # Capability Architecture — registry + capability pages
│   ├── registry/repo-registry.md     # Unified registry of all repos
│   ├── repos/                        # One digest per repo (e.g. shared-skills)
│   ├── ventures/                     # One digest per venture / system (layers)
│   ├── architecture/                 # System-of-systems, intelligence platform, principles, reuse map
│   ├── current-state/                # Status dashboard, changelog, roadmap
│   └── decisions/                    # Decision log / ADRs
├── showcase/                     # PUBLIC SHOWCASE LAYER (later target)
├── templates/                    # Canonical markdown page templates
├── design/                       # Design-system + brand-token placeholders
├── ai/                           # AI handoff files (Claude & ChatGPT)
└── skills/portfolio-portal-orchestrator/  # Spec for a future automation skill

Quick start for a human editor

  1. Read the Portfolio Overview — the executive briefing for the whole ecosystem.
  2. Read CLAUDE.md — it explains the maintenance rules for both humans and AI agents.
  3. Skim docs/information-architecture.md to understand the navigation model.
  4. To add a repo: copy templates/repo-digest.template.md into portal/repos/ and add a row to portal/registry/repo-registry.md.
  5. To add a venture: copy templates/venture-digest.template.md into portal/ventures/.
  6. Record any significant decision as an ADR in portal/decisions/.

Status

Phase D — ecosystem architecture review. With capability architecture in place, the portal now reviews itself: a holistic, evidence-first EA review — Architecture Review, Risks, Strategic Opportunities, and Recommended Architecture Evolution — with a proposed ADR 0005 introducing a Platform Services layer. Recommendations only; no architecture was modified. Earlier phases established the Capability Architecture (Phase C) and the four processed systems (Phases B). Still to come: adopting the review’s direction, full digests for the layer-4 consumer repos, the public showcase website, and the automation skill (spec only — see skills/portfolio-portal-orchestrator/SPEC.md).