Skip to main content

Portfolio Documentation System

Purpose​

This repository is the authoritative documentation system for the public portfolio program. It is intentionally structured to demonstrate enterprise-level capabilities in:

  • product and delivery planning
  • architecture and decision traceability
  • DevOps execution and operational readiness
  • secure SDLC and measurable security posture
  • documentation discipline suitable for dev and business stakeholders

This is not “notes.” It is a living, version-controlled evidence system.

Scope​

In scope​

  • end-to-end documentation for the portfolio web app as a production-like service
  • documentation for linked demo projects (each with a consistent dossier format)
  • delivery artifacts (roadmap, release notes, ADRs, runbooks, threat models, postmortems)
  • operational playbooks (deployment, rollback, incident response, DR/BCP)
  • engineering standards and reproducible local development practices

Out of scope​

  • private secrets or internal-only environment details
  • proprietary or sensitive data
  • unstructured “dumping ground” content without a defined section home

Audience​

  • Recruiters / Hiring Managers: a curated, legible narrative of capabilities and outcomes
  • Engineers / Technical Leads: deep technical detail, standards, and evidence of maturity
  • Security / Platform reviewers: threat models, controls, scans, and operational procedures
  • Developer & AI agents: a reliable system for planning and implementing changes

Start here (fast reviewer path)​

  1. Reviewer guide
  2. Portfolio App Development Roadmap
  3. Portfolio App Project Dossier
  4. Application evidence validation:

How this repository is organized​

Top-level domains (each has its own index.md and governance):

  • 00-portfolio/ — curated portfolio narrative (capabilities, roadmap, release notes)
  • 10-architecture/ — system design, C4 views, ADRs, integrations, data flows
  • 20-engineering/ — standards, local dev, testing strategy, dependency management
  • 30-devops-platform/ — CI/CD, environments, infra, observability, rollback strategy
  • 40-security/ — security posture, threat models, secure SDLC controls, evidence
  • 50-operations/ — runbooks, incident response, DR/BCP, service management
  • 60-projects/ — per-project dossiers (portfolio app + demos)
  • 70-reference/ — CLI/config references and quick operational diagnostics

Documentation governance model​

This repository follows a strict docs-as-code workflow:

  • PR-only changes to main (even for solo work)
  • Trunk-based workflow with short-lived branches
  • Required front matter on every doc
  • Required standardized page shape:
    1. Purpose
    2. Scope
    3. Prereqs / Inputs
    4. Procedure / Content
    5. Validation / Expected outcomes
    6. Failure modes / Troubleshooting
    7. References

Non-negotiable publication safety rules​

Never commit:

  • secrets, tokens, private keys
  • private IPs/internal hostnames
  • sensitive logs or customer-like data
  • any data you would not publish on a public website

Docs-driven delivery loop (how planning and implementation work here)​

For meaningful changes (feature, infra, security control), update artifacts in this order:

  1. Roadmap / intent (in 00-portfolio/)
  2. ADR (if architecture/platform/security impact exists) (in 10-architecture/adr/)
  3. Threat model + SDLC controls (in 40-security/)
  4. Ops readiness (runbooks, observability, rollback notes) (in 50-operations/ and 30-devops-platform/)
  5. Release notes (in 00-portfolio/release-notes/)

This loop ensures every “build” is paired with “run” and “secure.”

Contribution quickstart​

  1. Create a branch using an approved prefix (docs/sec/ops/arch/ci/ref).
  2. Author content using the section rules in the relevant domain index.md.
  3. Run local verification:
    • pnpm start for preview
    • pnpm build for production validation
  4. Submit a PR using the repository PR template and include build evidence.
  5. Merge only when checks pass.

Validation expectations​

A change is acceptable only if:

  • the documentation site builds successfully (pnpm build)
  • navigation remains coherent (categories and indexes are present)
  • new procedures include validation steps and rollback notes
  • security-sensitive changes include an explicit “no secrets added” statement

Create these foundational artifacts early:

  • portfolio product brief + capability map
  • system context (C4 L1) and a small set of ADRs
  • CI/CD pipeline overview + rollback strategy
  • threat model for the portfolio app + secure SDLC controls checklist
  • deploy and rollback runbooks, plus an incident triage runbook