Skip to main content

Portfolio Docs: Architecture

Purpose​

This page describes the Portfolio Docs App architecture at a practical level:

  • how content is structured and routed
  • how navigation is generated and governed
  • what components exist (content, configuration, deployment surface)
  • how the architecture supports enterprise documentation outcomes

Scope​

In scope​

  • content domain model and folder structure
  • navigation generation strategy (autogenerated sidebars + category metadata)
  • “public docs” vs “internal scaffolding” separation (docs/_meta)
  • diagram conventions and documentation lifecycle rules

Out of scope​

  • pipeline implementation details (see deployment.md)
  • threat enumeration and controls (see security.md)

Prereqs / Inputs​

  • A Docusaurus site with docs stored under docs/
  • An established top-level domain scaffold:
    • 00-portfolio / 10-architecture / 20-engineering / 30-devops-platform
    • 40-security / 50-operations / 60-projects / 70-reference
  • Internal authoring scaffolding stored in docs/_meta/

Procedure / Content​

System boundaries and components​

Core components​

  • Docs content (docs/):

    • all public-facing documentation content
    • organized by enterprise domains and project dossiers

  • Navigation governance:

    • sidebars.ts uses autogenerated based on filesystem
    • _category_.json inside navigable folders defines label, ordering, and landing behavior
    • top-level domains link to curated index.md hub pages

  • Site configuration:

    • docusaurus.config.ts defines global site settings and docs plugin behavior
    • Environment variables enable configuration portability:
      • DOCUSAURUS_SITE_URL (production domain vs local)
      • DOCUSAURUS_BASE_URL (root vs subpath)
      • DOCUSAURUS_GITHUB_* (GitHub links, edit URLs, navbars)
      • DOCUSAURUS_PORTFOLIO_APP_URL (cross-linking to portfolio-app)

Environment alignment​

  • The app’s staging tier is implemented via Vercel branch/domain mapping. Documentation can remain on a single production domain while the app uses NEXT_PUBLIC_DOCS_BASE_URL to link consistently.

  • If desired, a docs staging domain can be mapped to a docs branch for preview review. Keep linking environment-first and avoid hardcoding hosts.

    • Fallback values in config ensure robustness when environment files are absent
    • (optional) Mermaid enablement for diagrams, if adopted

  • Environment configuration:

    • .env.example: Template with placeholders (committed to repo)
    • .env.local: Local development overrides (gitignored, not committed)
    • .env.production.local: Production-specific overrides (gitignored, optional)
    • See Environment Variables Contract for full documentation

  • Static assets (static/):

    • images and diagrams, stored with stable names
    • optional evidence artifacts in sanitized form (if later added)

Internal-only authoring scaffolding​

  • docs/_meta/ is intentionally not public-facing.
  • It contains templates, style guides, taxonomy rules, and contributor instructions that should not clutter the public site.
  • Governance narrative (if desired publicly later) should be copied into a dedicated public section rather than renaming _meta.

Content domain model (enterprise scaffold)​

Top-level domains are designed to map to enterprise responsibilities:

  • 00-portfolio: narrative + roadmap + releases (human legibility)
  • 10-architecture: system design + ADR traceability (technical intent)
  • 20-engineering: build/test standards + local dev reproducibility
  • 30-devops-platform: CI/CD + environments + observability
  • 40-security: threat models + SDLC controls + supply chain posture
  • 50-operations: runbooks + IR + DR/BCP readiness
  • 60-projects: per-project dossiers (this section)
  • 70-reference: fast-access command and config references

This scaffold is designed to scale without becoming a “notes dump.”

Autogenerated sidebars​

  • The sidebar should be filesystem-driven, so new content appears without manual sidebar maintenance.
  • Governance is applied via:
    • consistent folder and file naming
    • _category_.json metadata for every navigable folder
    • consistent index.md hub pages for major sections

Category landing behavior​

  • Top-level domains use:
    • _category_.json → link.type: doc pointing to <domain>/index.md
  • Subsections default to:
    • _category_.json → link.type: generated-index until a curated hub is justified

This is the maintainability and reviewer-experience balance.

  • Use diagrams only when they reduce ambiguity.
  • Keep diagrams minimal (avoid “mega diagrams”).
  • Prefer Mermaid for flows/sequence diagrams (if enabled).
  • Store images under static/img/diagrams/ with stable filenames.

Documentation lifecycle (prevent drift)​

  • “Docs follow changes” rule:
    • if the structure or governance changes, update the affected indexes and _category_.json in the same PR
  • “No orphan knowledge” rule:
    • every new folder must have a category definition and an entrypoint (generated or curated)

Validation / Expected outcomes​

Architecture is correct when:

  • adding a new folder + _category_.json reliably produces coherent navigation
  • top-level domains present curated entrypoints for reviewers
  • internal templates remain non-public under docs/_meta/
  • the system can scale to a large documentation corpus without sidebar churn

Failure modes / Troubleshooting​

  • Sidebar unpredictability: ordering becomes confusing → enforce position in _category_.json and sidebar_position in key docs.
  • Category click leads nowhere: category has no link → add a doc link to index.md or a generated-index link.
  • Meta docs leak publicly: _meta renamed or moved → restore underscore prefix and keep internal-only scaffolding separated.

References​

  • Domain scaffolding: docs/index.md and top-level domain index.md pages
  • Internal-only governance scaffolding: docs/_meta/
  • This dossier category metadata: docs/60-projects/portfolio-docs-app/_category_.json