Skip to content

README.md

Latest commit

 

History

History
121 lines (93 loc) · 8.99 KB

README.md

File metadata and controls

121 lines (93 loc) · 8.99 KB
Raw

Smart Portfolio documentation

This documentation explains how Smart Portfolio is authored, built, tested, deployed, operated, and reviewed. The root project README is the visitor-facing overview. The guides here provide the implementation detail needed to change the system safely.

Documentation principles

  • Implementation is authoritative. Package scripts, application code, validators, Cloudflare Functions, and GitHub Actions take precedence over prose.
  • Public portfolio content and private runtime configuration are separate concerns.
  • A guide explains a system or procedure. A checklist provides a concise verification pass and links to its guide.
  • Shared facts should have one detailed home and be linked elsewhere instead of copied.
  • Documentation changes are part of the quality gate and must pass npm run docs:check.

Choose a path

Reader Start with Continue with
Portfolio owner or developer setting up a local copy Local development Agent workflow for repository changes, or local content editing for content updates
Agent or automated contributor Agent workflow Local development, the selected repository skill, and testing
Design contributor Design system Accessibility, animation guidelines, and skeleton loading guidelines
Deployment operator restoring this service or adapting a fork Deployment Operations, testing, and troubleshooting
Security reviewer Security Contact system, architecture, and security checklist

Dependency and setup contract

  1. Install a Node 22 release selected by .nvmrc that meets the minimum declared by package.json; the setup helper enforces that minimum.
  2. Use npm ci for a reproducible dependency installation. package-lock.json locks the exact dependency tree and must stay synchronized with package.json.
  3. Run the Windows npm run setup:local command or the cross-platform npm run setup:local:node command from Local development. The helper creates an ignored .env from .env.example, installs dependencies when required, and prepares local content.

This is an npm repository: package.json, package-lock.json, and .nvmrc are the dependency requirements. A separate requirements.txt would not be used by the application or CI.

Start here

Document Purpose
Project README Product overview, architecture summary, setup path, route map, and links into the documentation suite.
Architecture System boundaries, layers, data flow, tradeoffs, and authoritative implementation sources.
Project structure Repository tree, route ownership, component groups, tests, and guidance on where changes belong.

Content authoring

Document Purpose
Content pipeline Local and remote source modes, XLSX validation, normalization, generated JSON, and semantic hashing.
Content sheet schema Exact field reference for supported source data.
Content mapping Mapping from source fields through generated types and selectors to routes and components.
Local content editing Owner-focused procedure for editing local templates, assets, and workbook-backed content.
Content replacement checklist Short publication checklist for replacing portfolio content safely.
Research media Publication facts, accessibility artifacts, and integrity contracts for self-hosted Research media.

Design and user experience

Document Purpose
Design system Themes, tokens, solid surface primitives, layout, cards, interactions, and contribution rules.
Accessibility Accessibility practices, interaction contracts, known limits, and verification steps.
Animation guidelines Approved motion behavior, timing, reduced-motion handling, and interaction constraints.
Skeleton loading guidelines Route loading states, static-first constraints, layout matching, and accessibility behavior.

Development and quality

Document Purpose
Local development Supported Node.js version, setup commands, development servers, local content, and Pages Function testing.
Agent workflow Portable repository-local guidance, focused skills, durable decisions, and model routing.
Testing Test layers, focused commands, Playwright navigation, recommendation, and footer coverage, the full quality gate, CI behavior, and test-extension guidance.
Engineering standards Concise architecture, component, styling, test, and dependency rules.
Quality checklist General pre-merge verification checklist.
Repository reachability audit Evidence, retention decisions, and the removal standard for unused-code reviews.
Performance budget Runtime, JavaScript, asset, surface, motion, and build constraints.
Performance checklist Focused pre-merge performance review.

Deployment and operations

Document Purpose
Deployment GitHub and Cloudflare setup, environment separation, release governance, and first deployment.
Operations Event behavior, candidate selection, exact-artifact deployment, manifests, smoke tests, retries, and rollback considerations.
Troubleshooting Symptoms, likely causes, diagnostics, safe corrections, and actions to avoid.

Security and data handling

Document Purpose
Security Threat model, trust boundaries, public and private data, headers, URL rules, contact security, and publication review.
Contact system Client workflow, verification ticket, request validation, Turnstile, Resend, configuration, and abuse controls.
Security checklist Concise operational security review linked to the deeper guides.

Maintenance

Document Purpose
Maintenance Safe extension patterns for content fields, routes, UI, themes, Functions, CI, and deployment.

Sources of truth

Use the narrowest authoritative implementation source when documentation and code differ.

Topic Authoritative implementation
Dependencies, Node.js version, and commands package.json, package-lock.json, and .nvmrc
Static export and route implementation next.config.mjs and src/app/
Content types and runtime validation src/content/types.ts and src/lib/content/
Workbook download and structure scripts/fetchPortfolioContent.ts and scripts/lib/portfolioContentGeneration.ts
Home selection and section order src/lib/content/selectHomeContent.ts and src/components/portfolio/home/HomeOverview.tsx
Themes, layout, motion, and styling src/components/, src/lib/theme/, and src/styles/
Contact request boundary functions/api/, functions/_shared/contact.ts, and src/components/contact/
Function routing and static headers public/_routes.json and public/_headers
Cloudflare configuration wrangler.jsonc
Verification and deployment behavior .github/workflows/ci.yml and scripts/
License LICENSE

Keeping documentation synchronized

  1. Change implementation and tests together.
  2. Update the guide that owns the affected behavior.
  3. Update the concise checklist that verifies it, if one exists.
  4. Replace duplicated detail elsewhere with a descriptive link.
  5. Run npm run docs:check and the relevant focused tests.
  6. Run npm run verify before delivery.

When adding a document, give it one clear purpose, add it to the appropriate table above, and link it from the guide that introduces the concept. Do not publish secret values, the workbook URL, private recipient configuration, or machine-specific paths.