Documentation Pipeline Architecture

System Overview

graph TD subgraph main["MAIN BRANCH (Source of Truth)"] direction LR subgraph committed["✓ Committed"] src["src/"] docs["docs/"] scripts["scripts/build-arch-docs.sh"] configs["package.json
typedoc.json
vitest.config.ts
.github/workflows/
.dockerignore
.gitignore
Dockerfile
README.md"] end subgraph generated["✗ Not Committed (gitignore)"] dist["dist/ (Vite build)"] coverage["coverage/ (Test coverage)"] publicdocs["public-docs/ (Generated docs)"] nodemodules["node_modules/"] end subgraph generated2["Generated by npm run docs:all"] publicdocs2["public-docs/index.html
public-docs/architecture/*.html
public-docs/typedoc/
public-docs/coverage/
public-docs/templates/*.css"] end end main --> deploy["deploy-frontend.yml"] main --> docspipe["docs-pipeline.yml"] deploy --> vercel["VERCEL PRODUCTION
https://stockease-...vercel.app/"] docspipe --> ghpages["GITHUB PAGES gh-pages
https://keglev.github.io/stockease-frontend/"] vercel --> vContent["✓ dist/ production app
✗ .md files
✗ Test files
✗ Documentation source"] ghpages --> ghContent["✓ public-docs/index.html
✓ Architecture HTML
✓ TypeDoc API
✓ Coverage reports
✗ Source files
✗ node_modules"] style main fill:#e1f5ff style vercel fill:#c8e6c9 style ghpages fill:#fff9c4 style vContent fill:#c8e6c9 style ghContent fill:#fff9c4

File Generation Pipeline

graph TD docall["npm run docs:all"] docall --> clean["npm run docs:clean"] docall --> arch["npm run docs:arch"] docall --> typedoc["npm run docs:typedoc"] docall --> coverage["npm run docs:coverage"] docall --> landing["npm run docs:landing"] clean --> cleanout["Remove public-docs
Create public-docs/
├── architecture/
├── typedoc/
└── coverage/"] arch --> archconv["Pandoc
Converts markdown → HTML
Uses template
Applies CSS
Adds TOC"] archconv --> archout["Output:
public-docs/architecture/"] typedoc --> typedocconv["TypeDoc
Generates from source code
├── index.html
├── Search
├── API docs
└── Modules"] typedocconv --> typedocout["Output:
public-docs/typedoc/"] coverage --> covconv["Vitest
Generates coverage report
├── index.html
└── Coverage data"] covconv --> covout["Output:
public-docs/coverage/"] landing --> landingconv["Node.js
Converts docs/index.md → index.html
Uses template + CSS
Creates landing page"] landingconv --> landingout["Output:
public-docs/index.html"] cleanout --> final["public-docs/ Final Output
├── index.html
├── architecture/ (all sections)
├── typedoc/ (API docs)
├── coverage/ (test reports)
└── templates/ (CSS)"] archout --> final typedocout --> final covout --> final landingout --> final final --> ghpages["Publish to gh-pages
via peaceiris/actions-gh-pages@v3"] ghpages --> deployed["GitHub Pages
https://keglev.github.io/stockease-frontend/"] style docall fill:#bbdefb style final fill:#c8e6c9 style deployed fill:#fff9c4

Workflow Decision Tree

graph TD push["Push to main"] push --> checkdeploy["deploy-frontend.yml
Always runs
Irrelevant of paths"] push --> checkdocs["docs-pipeline.yml
Conditional path-based"] checkdeploy --> deploy1["1. Test npm test"] deploy1 --> deploy2["2. Build npm run build"] deploy2 --> deploy3["3. Docker verify"] deploy3 --> deploy4["4. Deploy to Vercel"] deploy4 --> deployout["Output: dist/ → Vercel
Duration: 3-5 minutes"] checkdocs --> fileschanged{{"Changed files
include:
docs/**
src/**
*.json config
vitest.config.ts"}} fileschanged -->|YES| docsbuild["1. Build arch docs
2. Generate TypeDoc
3. Generate coverage
4. Build landing page
5. Publish to gh-pages"] fileschanged -->|NO| docsskip["SKIP"] docsbuild --> docsout["Output: public-docs/ → gh-pages
Duration: 2-4 minutes"] style push fill:#bbdefb style deployout fill:#c8e6c9 style docsout fill:#fff9c4 style docsskip fill:#ffccbc

Security & Isolation

graph LR subgraph prod["Production Pipeline deploy-frontend.yml"] p1["Input:
main branch
complete source"] p2[".dockerignore
excludes:
docs/
*.md
**/__tests__
.github/
Coverage files"] p3["Docker copies:
src/
public/
config files only"] p4["Builds:
dist/
production bundle"] p5["Result:
Lean image
no docs"] p6["Deployed to:
Vercel"] end subgraph doc["Documentation Pipeline docs-pipeline.yml"] d1["Input:
main branch
only when relevant
files change"] d2["Generates:
public-docs/
temporary"] d3["Runs:
npm run docs:all
Pandoc markdown→HTML
TypeDoc source→API docs
Vitest coverage→reports
Landing index.md→HTML"] d4["Publishes:
public-docs/→gh-pages
only"] d5["Result:
Clean documentation
site"] d6["Served at:
GitHub Pages"] end subgraph results["Separation Results"] r1["✅ No docs in production"] r2["✅ No code in docs"] r3["✅ Different deployment"] r4["✅ Different builds"] r5["✅ Different access"] end p1 --> p2 --> p3 --> p4 --> p5 --> p6 d1 --> d2 --> d3 --> d4 --> d5 --> d6 p6 --> results d6 --> results style prod fill:#c8e6c9 style doc fill:#fff9c4 style results fill:#e1bee7

Caching & Performance

graph TD subgraph browser["Client Browser"] b1["Landing page:
No cache
checks for updates"] b2["Architecture pages:
Browser cache
mostly static"] b3["TypeDoc pages:
Browser cache
generated once
per src change"] b4["Coverage pages:
Browser cache
generated per
test run"] b5["Static assets CSS JS:
Pandoc-generated CSS
Browser cache
Mermaid.js CDN:
CDN cache"] end subgraph github["GitHub Pages"] g1["Serves static
HTML directly"] g2["Uses HTTP/2"] g3["GZIP compression
enabled"] g4["CDN caching
Cloudflare"] g5["Edge locations
worldwide"] end subgraph vercel["Production Vercel"] v1["React app:
Dynamic
Next.js-like behavior"] v2["Static files:
Vercel edge cache"] v3["API proxying:
Dynamic
to backend"] v4["Auto-scaling:
Serverless functions"] end style browser fill:#c8e6c9 style github fill:#fff9c4 style vercel fill:#f8bbd0

Change Detection Logic

docs-pipeline.yml triggers when:

Trigger	Action	Result
`docs/architecture/*.md` changed	✅ Rebuild architecture HTML	Docs updated
`src/.ts` or `src/.tsx` changed	✅ Regenerate TypeDoc	API docs updated
`vitest.config.ts` changed	✅ Rebuild with new config	Coverage updated
`typedoc.json` changed	✅ Rebuild with new config	API docs updated
`package.json` or `package-lock.json` changed	✅ Rebuild	Dependencies may affect docs
Only tests changed `*.test.ts`	⏭️ SKIPPED	No docs rebuild needed
Only linting changed `.eslintrc`	⏭️ SKIPPED	No docs rebuild needed
Only production code `src/main.tsx`	⏭️ SKIPPED	No docs rebuild needed
Only workflows changed	⏭️ SKIPPED	No docs rebuild needed

This prevents unnecessary documentation rebuilds when they're not needed.

Link Resolution Logic

Generated HTML uses JavaScript to resolve paths dynamically:

function getRootFrom(pathname) {
  // Example paths:
  // /stockease-frontend/index.html
  //   → root = ./
  // /stockease-frontend/architecture/overview.html
  //   → root = ../
  // /stockease-frontend/architecture/api/overview.html
  //   → root = ../../
  
  // Works under any subdomain:
  // https://keglev.github.io/stockease-frontend/ ✅
  // https://custom.com/docs/stockease/ ✅
  // https://docs.stockease.example.com/ ✅
}

CSS Path: ${root} + templates/frontend-docs.css
Home Link: ${root} + index.html
API Link: ${root} + typedoc/index.html
Coverage Link: ${root} + coverage/index.html

Summary

This architecture provides:

✅ Complete Separation: Docs and production never mix
✅ Automated Generation: All docs built on every relevant change
✅ Targeted Triggers: Only runs when needed
✅ Clean Distribution: Each system gets exactly what it needs
✅ Security: No documentation in production code
✅ Performance: Lean images, efficient pipelines
✅ Scalability: GitHub Pages handles docs, Vercel handles app
✅ Maintenance: Single source of truth (main branch)

Generated: November 12, 2025