Skip to main content

Project Dossier: Portfolio Docs App

Dossier Contents​

Purpose​

This dossier documents the Portfolio Docs App: a Docusaurus-based, docs-as-code platform that serves as the portfolio program’s public-facing documentation system.

The Portfolio Docs App is treated as a production-like service to demonstrate:

  • enterprise documentation information architecture and governance
  • documentation-as-code delivery discipline (PRs, CI, quality gates)
  • security posture appropriate for a public site (supply chain, secrets hygiene, build integrity)
  • operational readiness (deploy/rollback/runbooks, maintenance, recovery assumptions)

This dossier is intentionally written as a microcosm of how the larger portfolio web app and demo ecosystem will be documented.

Scope​

In scope​

  • what the Portfolio Docs App is and what it proves
  • architecture and content domain model
  • deployment model and pipeline contract
  • security posture (threat surface + enforceable SDLC controls)
  • “testing” for docs: build/link integrity/lint/format
  • operations: runbooks, maintenance cadence, recovery expectations
  • troubleshooting for common Docusaurus/docs-as-code failure modes

Out of scope​

  • full portfolio web app product documentation (documented as its own dossier later)
  • detailed hosting vendor-specific secrets or account configuration
  • any internal-only authoring scaffolding stored under docs/_meta/ (non-public)

Prereqs / Inputs​

  • Repository baseline:
    • Docusaurus (TypeScript) project using pnpm
    • filesystem-driven docs under docs/
    • autogenerated sidebar strategy (recommended)
  • Working environment:
    • Windows 11 + WSL2 (Ubuntu) + VS Code Remote-WSL
  • Governance baseline:
    • PR-only merges to main
    • docs build must succeed (pnpm build) prior to merge
    • publication safety rules enforced (no secrets, no internal endpoints)

Procedure / Content​

Dossier structure (this folder)​

This dossier is organized as a set of reviewer-navigable pages:

  • overview.md — product framing, goals, NFRs, and evidence map
  • architecture.md — system design and content domain model
  • deployment.md — CI/CD contract, environments, hosting, release discipline
  • security.md — threat surface, SDLC controls, supply chain posture
  • testing.md — quality gates for docs (build/link/lint/format)
  • operations.md — runbooks, maintenance, DR assumptions, ownership
  • troubleshooting.md — common problems + deterministic fixes

Where supporting enterprise artifacts live​

This dossier references and depends on domain-level artifacts:

  • ADRs: docs/10-architecture/adr/
  • Threat models: docs/40-security/threat-models/
  • Runbooks: docs/50-operations/runbooks/
  • Pipeline and platform docs: docs/30-devops-platform/
  • Style and taxonomy (internal-only): docs/_meta/

Validation / Expected outcomes​

This dossier is considered “complete enough for first publication” when:

  • the dossier pages exist and follow the standard page shape
  • the docs site builds successfully (pnpm build)
  • navigation is coherent:
    • category metadata exists at docs/60-projects/portfolio-docs-app/_category_.json
    • this hub page is the category landing page
  • claims in these pages map to concrete governance/pipeline/security/ops artifacts (even if some artifacts are initially stubbed)

Current Capability Snapshot​

  • Docs infrastructure: Docusaurus + TypeScript configured for enterprise authoring patterns
  • Architecture and governance: 7-page dossier with threat model, security analysis, and operational baseline
  • CI/CD pipeline: Quality gates (lint, format check, link validation); build determinism enforced with frozen lockfiles; branch protection via required checks
  • Security hardening plan: ADR-0019 and the docs hardening implementation plan are published; audit gates and header validation are tracked via the security program
  • Testing and validation: Build/link/lint/format quality gates with local pnpm verify workflow
  • Operational procedures: Comprehensive runbooks and governance documentation in docs/50-operations/runbooks/
    • Project Publish Runbook: Time-boxed procedure for portfolio app project publication
      • Covers planning, registry entry, dossier update, link validation, PR/review, and post-publish checks
      • Validation signals: pnpm registry:validate, pnpm links:check, pnpm build
      • Includes rollback and abort procedures
    • Troubleshooting Guide: Common project-publication failure modes with diagnostic steps
      • Covers invalid slugs, broken dossier links, missing evidence URLs, schema validation failures, and CI link-validation flakiness
      • References playwright-report artifacts from CI for debugging

Failure modes / Troubleshooting​

  • Dossier pages drift into general policy (belongs in domain sections) → refactor content into the appropriate domain and keep dossier as project-specific summary.
  • The dossier becomes marketing-only → add validation procedures and operational/security evidence.
  • The dossier references artifacts that do not exist yet → remove links, add path references, and create the missing artifacts via tracked work.

References​

  • Project dossier standard: docs/60-projects/index.md
  • Documentation governance and templates (internal-only): docs/_meta/
  • Required domain references (create/maintain as needed):
    • ADRs: docs/10-architecture/adr/
    • Threat models: docs/40-security/threat-models/
    • Runbooks: docs/50-operations/runbooks/
    • CI/CD overview: docs/30-devops-platform/ci-cd/