Skip to main content

Project Dossier: Portfolio App

Dossier Contents​

Purpose​

This dossier documents the Portfolio App: a production-quality TypeScript web application that serves as:

  • an interactive CV and professional public landing experience
  • a platform to showcase projects (Python, Java, C++, etc.) with strong evidence and reproducibility
  • a working exemplar of enterprise SDLC, including CI quality gates, security hygiene, and operational readiness

The Portfolio App is intentionally paired with the Portfolio Documentation App (Docusaurus), which serves as the evidence engine for deep technical documentation, governance artifacts, and operational procedures.

Scope​

In scope​

  • architecture and content model for the Portfolio App
  • deployment model and release governance (Vercel + checks)
  • quality gates (lint/format/typecheck/build; tests phased)
  • security posture for a public site with no authentication
  • operations posture: runbooks, troubleshooting, DR assumptions

Out of scope​

  • authentication/authorization (explicitly deferred)
  • contact form and backend services (deferred; static contact mechanism only)
  • complex data stores (initially static content / lightweight data sources)

Prereqs / Inputs​

  • Portfolio program documentation system exists (Docusaurus)
  • GitHub repository for Portfolio App with PR discipline and CI gates
  • Hosting: Vercel (preview + production), with production on the root domain
  • Docs hosting: Documentation App on /docs or a docs subdomain

Procedure / Content​

Dossier structure (this folder)​

  • overview.md — product framing, scope, NFRs, evidence map
  • architecture.md — system design, content model, component boundaries
  • deployment.md — CI/CD contract, environments, release governance, domains
  • security.md — threat surface and enforceable controls (public-safe)
  • testing.md — quality gate definitions and test strategy (phased)
  • operations.md — runbooks, maintenance cadence, recovery assumptions
  • troubleshooting.md — common failure modes and deterministic fixes

Relationship to the Documentation App​

  • Portfolio App: “front-of-house” product experience (fast, polished)
  • Documentation App: “enterprise evidence engine” (ADRs, threat models, runbooks, dossiers)

Portfolio App must link to evidence pages for each project:

  • “Read the dossier”
  • “See the threat model”
  • “View runbooks / release notes”

Current Capability Snapshot​

  • Core route surface: /, /cv, /projects, /projects/[slug], /contact.
  • CI gates enforced: ci / quality and ci / build with required checks and frozen lockfile installs.
  • Evidence artifacts are maintained as first-class deliverables: ADRs, threat model, runbooks, and dossier pages.
  • Observability and operational readiness are documented with health checks and MTTR runbooks.
  • UX/SEO/theming capabilities are documented with references and decision records.

Evidence map (review-first)​

Reviewer path​

  • Open the Portfolio App repo and inspect CI workflows (ci, CodeQL, Dependabot) for required checks and naming stability.
  • Review PR discipline and branch protection/ruleset settings to confirm required checks are enforced.
  • Validate build determinism locally with pnpm lint, pnpm format:check, pnpm typecheck, pnpm build (frozen lockfile).
  • Follow evidence links from the app into this dossier, ADR index, threat model, and runbooks to confirm traceability.
  • Review the Threat Model to understand security assumptions and mitigations across STRIDE categories.

Validation / Expected outcomes​

  • A reviewer can understand value, role, and proof within 2 minutes
  • The app is deployable with reproducible builds and CI gating
  • Every showcased project links to documented evidence and reproducible steps
  • Governance artifacts exist and are maintained as the app evolves

Failure modes / Troubleshooting​

  • Broken deployments due to routing/base path mismatch → see deployment.md + runbooks
  • Build failures due to lint/format/typecheck drift → see testing.md
  • Content drift / stale project pages → enforce release notes and dossier updates

References​

  • Documentation App (evidence engine): docs/60-projects/portfolio-docs-app/
  • ADRs: docs/10-architecture/adr/
  • Threat models: docs/40-security/threat-models/
  • Runbooks: docs/50-operations/runbooks/
  • Release notes: docs/00-portfolio/release-notes/