Information Architecture & Navigation Model

This page defines the page hierarchy, navigation, and routing model for the Portfolio Architecture Portal. It is the output of the site-architecture skill applied to a documentation/hybrid portal. It governs both the current markdown structure and the eventual public showcase site.

Audiences & goals

The three IA layers

The portal maps onto the three-layer design principle. Navigation should never blur these layers.

graph TD
    subgraph L3["Public Showcase (Phase C — later)"]
        SHOW[Showcase Home]
    end
    subgraph L2["Portfolio Portal (this repo — system of systems)"]
        HOME[Portal Home]
        REG[Repo Registry]
        VEN[Ventures]
        REPOS[Repos]
        ARCH[Architecture]
        STATE[Current State]
        DEC[Decisions / ADRs]
    end
    subgraph L1["Repo-level docs (in each source repo)"]
        RD[README / docs / ADRs / CLAUDE.md]
    end

    HOME --> REG
    HOME --> VEN
    HOME --> ARCH
    HOME --> STATE
    HOME --> DEC
    REG --> REPOS
    VEN --> REPOS
    REPOS -.digest of.-> RD
    SHOW -.curated from.-> L2

Page hierarchy (ASCII tree)

Routes are the eventual public/site routes; the current markdown file backing each node is shown in parentheses.

Portal Home (/)                                   (portal/index.md)
├── Portfolio Overview (/overview)                (portal/portfolio-overview.md)  ← executive briefing
├── Ventures (/ventures)                          (portal/ventures/README.md)
│   └── Venture digest (/ventures/{slug})         (portal/ventures/{slug}.md)
├── Repos (/repos)                                (portal/repos/README.md)
│   ├── Repo registry (/repos/registry)           (portal/registry/repo-registry.md)
│   └── Repo digest (/repos/{slug})               (portal/repos/{slug}.md)
├── Capabilities (/capabilities)                  (portal/capabilities/README.md)  ← Capability Registry
│   └── Capability page (/capabilities/{slug})    (portal/capabilities/cap-{slug}.md)
├── Operating Model (/operating-model)            (portal/operating-model/README.md)
│   ├── Knowledge Asset Lifecycle                 (portal/operating-model/knowledge-asset-lifecycle.md)
│   ├── Concept Ownership Registry                (portal/operating-model/concept-ownership.md)
│   ├── Portfolio Glossary (authoritative)        (portal/operating-model/glossary.md)
│   ├── Context Architecture                      (portal/operating-model/context-architecture.md)
│   ├── Operating Principles                      (portal/operating-model/operating-principles.md)
│   └── AI Collaboration Model                    (portal/operating-model/ai-collaboration-model.md)
├── Architecture Governance (/governance)         (portal/governance/README.md)
│   ├── Capability Decision Framework             (portal/governance/capability-decision-framework.md)
│   ├── Capability Decision Matrix                (portal/governance/capability-decision-matrix.md)
│   ├── Repository Lifecycle                      (portal/governance/repository-lifecycle.md)
│   ├── Documentation Governance                  (portal/governance/documentation-governance.md)
│   ├── AI Governance                             (portal/governance/ai-governance.md)
│   └── Architecture Review Lifecycle             (portal/governance/architecture-review-lifecycle.md)
├── Architecture (/architecture)                  (portal/architecture/system-of-systems.md)
│   ├── System context (layered)                  (# section: Mermaid)
│   ├── Container / service map                   (# section: Mermaid)
│   ├── Layer / system map                        (# section: Mermaid)
│   ├── System dependency map                     (# section: Mermaid)
│   ├── Intelligence Platform (/architecture/intelligence-platform)  (portal/architecture/intelligence-platform.md)
│   ├── Architecture Principles (/architecture/principles)           (portal/architecture/principles.md)
│   ├── Capability Reuse Map (/architecture/capability-reuse-map)    (portal/architecture/capability-reuse-map.md)
│   ├── Architecture Review (/architecture/architecture-review)      (portal/architecture/architecture-review.md)
│   ├── Architecture Risks (/architecture/architecture-risks)        (portal/architecture/architecture-risks.md)
│   ├── Strategic Opportunities (/architecture/strategic-opportunities) (portal/architecture/strategic-opportunities.md)
│   ├── Architecture Evolution (/architecture/architecture-evolution)   (portal/architecture/architecture-evolution.md)
│   └── Review recommendations (/architecture/recommendations)       (portal/architecture/recommendations.md)
├── Current State (/state)                        (portal/current-state/status-dashboard.md)
│   ├── Status dashboard                          (portal/current-state/status-dashboard.md)
│   ├── Changelog (/state/changelog)              (portal/current-state/changelog.md)
│   └── Roadmap (/state/roadmap)                  (portal/current-state/roadmap.md)
├── Decisions (/decisions)                        (portal/decisions/README.md)
│   └── ADR (/decisions/{nnnn})                   (portal/decisions/{nnnn}-*.md)
├── Docs / About the portal (/about)              (docs/*.md)
│   ├── Information architecture                   (docs/information-architecture.md)
│   ├── Documentation model                        (docs/documentation-model.md)
│   ├── Update conventions                          (docs/update-conventions.md)
│   └── Glossary                                    (docs/glossary.md)
└── Showcase (/showcase) [Phase C — placeholder]  (showcase/README.md)

Depth stays within the 3-click rule: any repo digest, venture, diagram, or ADR is reachable within 3 clicks of the portal home.

Route / URL map

URL rules: lowercase, hyphenated slugs, no dates in paths, path mirrors hierarchy, slugs are stable (a repo/venture slug never changes once published — supersede via an ADR if it must).

Navigation model

Primary (header) nav

Portal Home · Overview · Capabilities · Repos · Ventures · Architecture · State · Decisions (Capabilities and Repos are the two primary catalogue entry points.)

Section (sidebar) nav

• Within Repos: registry first, then digests grouped by venture.
• Within Ventures: venture list, each linking to its member repos.
• Within Decisions: reverse-chronological ADR list.

Footer nav

• Portal: Home, Registry, Architecture, State
• About: IA, Documentation model, Update conventions, Glossary
• Meta: CLAUDE.md, llms.txt, Orchestrator spec

Breadcrumbs

Mirror the route hierarchy, e.g. Home > Repos > {repo} and Home > Ventures > {venture}.

Internal linking rules (portal-specific)

1. No orphan digests — every repo digest is linked from the registry and from at least one venture.
2. Bidirectional venture ↔ repo links — a venture lists its repos; each repo names its venture.
3. Architecture pages link to the digests of every node they draw, and vice versa.
4. ADRs backlink to the pages/diagrams they affect; affected pages link forward to the ADR.
5. Descriptive anchor text; never “click here”.

Change control for the IA

The structure on this page is itself governed by ADRs. Changing the layer model, the top-level nav, or the routing scheme requires an ADR in portal/decisions/. Do not restructure folders ad hoc — see docs/update-conventions.md.