LEO0331 Engineering Portfolio

English | 繁體中文

A production-ready, recruiter-friendly portfolio for LEO0331. The site is driven by curated project data, supports English and Traditional Chinese routes, and deploys statically to GitHub Pages.

Architecture and stack

• React 18 and TypeScript
• React Router 7 with static route entrypoints for GitHub Pages
• Vite 8 and Tailwind CSS
• Playwright E2E tests with a functional coverage gate
• GitHub Actions for build, Lighthouse, E2E, and Pages deployment

Why this structure

• Built for quick recruiter scanning: clear sections, focused project cards, direct demo/repo links
• Data-driven content: update portfolio info in data files, not JSX
• Bilingual ready: English + Traditional Chinese UI and project content support
• Static deployment: crawlable routes with generated GitHub Pages entrypoints
• Quality guardrails: Playwright E2E + CI workflows

What visitors can do

• Review who you are and your engineering focus
• Filter projects by category, technology, and status
• Open project details in-page without losing filters/scroll state
• Switch language between English and Traditional Chinese
• Open live demos and source repositories directly

Quick start

npm install
npm run dev

Build and test

The existing Tailwind 3 toolchain uses an npm override for postcss-selector-parser 7.1.6 to fix GHSA-rj75-hqrm-r3gf without a Tailwind 4 migration. Keep the override until the parent dependencies request a patched version themselves; regenerate the lockfile and run the full gate when changing it. A subprocess regression checks the malicious flat-selector case.

npm run validate:harness
npm ci
npm audit
npm run build
npm run test:e2e

Deploy to GitHub Pages

1. Confirm base in vite.config.ts matches the deployed repo path.
2. Build with your public site URL so sitemap and robots metadata are generated correctly:
   • SITE_URL=https://<username>.github.io/<repo> npm run build
   • this auto-generates both public/sitemap.xml and public/robots.txt
   • for security, only http/https SITE_URL values are accepted
3. Push to main.
4. In repository settings, enable GitHub Pages with GitHub Actions.

SEO (lightweight and automated)

• Route-level metadata is handled by usePageSeo in src/utils/seo.ts.
• public/sitemap.xml is auto-generated from src/routes/routeConfig.json during build.
• public/robots.txt is auto-generated from SITE_URL during build.
• After deployment, submit:
  • https://<username>.github.io/<repo>/sitemap.xml to Google Search Console
  • same URL to Bing Webmaster Tools

Update your portfolio content

Profile and skills

• src/data/profile.ts
• src/data/skills.ts

Projects (English + Traditional Chinese)

1. Run npm run sync:projects to preview GitHub metadata changes. New repositories are listed as review-only candidates and are never inserted automatically. Use npm run sync:projects -- --write only for reviewed demo URL updates to existing entries; curated descriptions are never overwritten.
2. Curate the canonical project record in src/data/projects.ts; do not keep automatically generated placeholder copy.
3. Add/update Traditional Chinese text in src/data/projects.zh.ts, including descriptions, roles, categories, features, and any challenges/outcomes. Use the optional name field for Chinese display titles. Every current project has translated copy; missing future entries fall back to the canonical English record.
4. Add the live-demo preview to src/assets/images/projects/<id>.png (or .webp) and visually verify that data-heavy pages finished loading.
   • Capture automation only visits public hosts approved in tools/public-demo-url.mjs; review and explicitly add custom deployment domains.
5. Capture selected previews in PowerShell:

$env:TARGET_IDS="project-id,another-id"
node tools/capture-project-previews.mjs

6. Update progress.md in the same change with the IDs added, sources checked, files changed, verification evidence, blockers, and next action.
7. Run the full verification gate shown above plus git diff --check.

Notes:

• If demoUrl is missing, the Live Demo button is hidden.
• If repoUrl is missing, the GitHub Repo button is hidden.
• If image is missing, cards render a graceful placeholder.

Homepage featured projects

The homepage follows the public GitHub pin order saved in src/data/github-pins.json. Pins map to stable project IDs so both languages show the same projects in the same order, including after repository renames. Only uniquely matched catalogue records appear. Unmatched pins (including this portfolio) and ambiguous monorepo pins are flagged for curation; no placeholders or unrelated filler cards are added. An empty pin list displays no featured cards.

Run npm run sync:pins with GITHUB_TOKEN to query GraphQL, save public pins/matched IDs, and update existing featured flags. The monthly scan performs the same sync using canonical repository URLs to handle renames. API errors preserve the last successful snapshot and fail the job. Rendering needs no network request or token. The initial snapshot was verified against the public profile on 2026-10-06: six pins, five catalogue matches, with LEO0331/portfolio intentionally unlisted.

Monthly project maintenance

Monthly Project Maintenance runs on the first of each month at 09:17 Asia/Taipei and can also be started from Actions → Monthly Project Maintenance → Run workflow. The schedule becomes active after the workflow is pushed to the default branch. In Settings → Actions → General, enable Allow GitHub Actions to create and approve pull requests; no additional API key is needed.

The scanner compares repository push timestamps, canonical URLs, descriptions, homepages, default branches, archive status, and root README hashes. It follows repository redirects, handles monorepo links, and paginates the owner's public repositories to list unlisted candidates. The first run records a baseline and opens a draft review PR; later runs open or update that PR only when tracked changes exist. An open maintenance branch is reused without force-pushing, preserving pending curation; merge conflicts stop the job for review.

Approved demo URL updates to existing root-repository projects are proposed automatically. Names, renamed repository links, bilingual copy, new projects, and previews require source/visual review in the draft PR. Changes on the live site without a GitHub push or metadata change are not detected. Merge the curated PR to main to publish through the existing Pages workflow.

The job runs harness validation, unit tests, TypeScript/build, E2E, and diff checks before pushing. Dependency audit findings are attached to the PR/run as advisory results so a security advisory cannot hide project-change findings; resolve them before release. Scan/API errors fail the job without writing a partial baseline. Reports and audit output are uploaded as artifacts. GitHub may delay scheduled runs and disables schedules in inactive public repositories after 60 days; re-enable the workflow in Actions if needed. Additional workflows triggered by the built-in token may require approval, so verification runs inside this job.

Run node tools/scan-project-changes.mjs locally with GITHUB_TOKEN (required for GraphQL pins). It writes .github/project-scan-state.json, .github/project-scan-report.md, src/data/github-pins.json, and proposed demo URLs/featured flags; review these together before accepting the baseline. Pin selections are included in the draft PR.

GitHub references: scheduled workflow behavior and token-triggered workflow behavior.

Documentation

• Traditional Chinese README: README.zh-TW.md
• Repository agent rules: AGENTS.md
• Feature state: feature_list.json
• Restartable work log: progress.md
• Current-session handoff: session-handoff.md
• Full verification entrypoint for Git Bash/CI (bash init.sh): init.sh
• Workflow skill template: skill.md
• Template usage guide: wiki.md