From e922ce64b88ec54be9f9ae4df99c15f41d981bc1 Mon Sep 17 00:00:00 2001 From: "dong.nguyen" Date: Tue, 6 Oct 2026 12:24:55 +0700 Subject: [PATCH] docs: add spec_v1.md (v1 completion record) and move all specs to docs/design/ --- AGENTS.md | 13 + .../design/spec-ui-about.md | 0 .../design/spec-ui-blog.md | 0 .../design/spec-ui-components.md | 0 .../design/spec-ui-contact.md | 0 .../design/spec-ui-engineering.md | 0 .../design/spec-ui-experience.md | 0 .../design/spec-ui-expertise.md | 0 .../design/spec-ui-footer.md | 0 .../design/spec-ui-hero.md | 0 .../design/spec-ui-layout.md | 0 .../design/spec-ui-navigation.md | 0 .../design/spec-ui-project-detail.md | 0 .../design/spec-ui-projects-list.md | 0 .../design/spec-ui-projects.md | 0 docs/design/spec-v2.md | 441 ++++++++++++++++++ spec.md => docs/design/spec.md | 0 docs/design/spec_v1.md | 174 +++++++ 18 files changed, 628 insertions(+) rename spec-ui-about.md => docs/design/spec-ui-about.md (100%) rename spec-ui-blog.md => docs/design/spec-ui-blog.md (100%) rename spec-ui-components.md => docs/design/spec-ui-components.md (100%) rename spec-ui-contact.md => docs/design/spec-ui-contact.md (100%) rename spec-ui-engineering.md => docs/design/spec-ui-engineering.md (100%) rename spec-ui-experience.md => docs/design/spec-ui-experience.md (100%) rename spec-ui-expertise.md => docs/design/spec-ui-expertise.md (100%) rename spec-ui-footer.md => docs/design/spec-ui-footer.md (100%) rename spec-ui-hero.md => docs/design/spec-ui-hero.md (100%) rename spec-ui-layout.md => docs/design/spec-ui-layout.md (100%) rename spec-ui-navigation.md => docs/design/spec-ui-navigation.md (100%) rename spec-ui-project-detail.md => docs/design/spec-ui-project-detail.md (100%) rename spec-ui-projects-list.md => docs/design/spec-ui-projects-list.md (100%) rename spec-ui-projects.md => docs/design/spec-ui-projects.md (100%) create mode 100644 docs/design/spec-v2.md rename spec.md => docs/design/spec.md (100%) create mode 100644 docs/design/spec_v1.md diff --git a/AGENTS.md b/AGENTS.md index 4c5fe75..4b5daf4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -88,6 +88,19 @@ src/ 4. **Theme from system:** When stored theme is `'system'`, `cycleTheme` must skip to opposite theme on first click (not go to `'dark'` which resolves to same visual) 5. **Footer/Nav links:** Must use ``, not `` for client-side navigation +## Design Specs + +All specification documents are in `docs/design/`: + +| File | Purpose | +|------|---------| +| `spec.md` | Main PRD — product vision, positioning, narrative, IA, acceptance criteria | +| `spec_v1.md` | v1 completion record — features implemented, known limitations, files summary | +| `spec-v2.md` | v2 features — Resume, Blog, SEO, Analytics, Testing, CI/CD | +| `spec-ui-*.md` | UI specs per section (hero, about, expertise, etc.) | + +Read `spec.md` first for product context. Read `spec-v2.md` for current feature scope. + ## Code Style & Linting - TypeScript: `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch` diff --git a/spec-ui-about.md b/docs/design/spec-ui-about.md similarity index 100% rename from spec-ui-about.md rename to docs/design/spec-ui-about.md diff --git a/spec-ui-blog.md b/docs/design/spec-ui-blog.md similarity index 100% rename from spec-ui-blog.md rename to docs/design/spec-ui-blog.md diff --git a/spec-ui-components.md b/docs/design/spec-ui-components.md similarity index 100% rename from spec-ui-components.md rename to docs/design/spec-ui-components.md diff --git a/spec-ui-contact.md b/docs/design/spec-ui-contact.md similarity index 100% rename from spec-ui-contact.md rename to docs/design/spec-ui-contact.md diff --git a/spec-ui-engineering.md b/docs/design/spec-ui-engineering.md similarity index 100% rename from spec-ui-engineering.md rename to docs/design/spec-ui-engineering.md diff --git a/spec-ui-experience.md b/docs/design/spec-ui-experience.md similarity index 100% rename from spec-ui-experience.md rename to docs/design/spec-ui-experience.md diff --git a/spec-ui-expertise.md b/docs/design/spec-ui-expertise.md similarity index 100% rename from spec-ui-expertise.md rename to docs/design/spec-ui-expertise.md diff --git a/spec-ui-footer.md b/docs/design/spec-ui-footer.md similarity index 100% rename from spec-ui-footer.md rename to docs/design/spec-ui-footer.md diff --git a/spec-ui-hero.md b/docs/design/spec-ui-hero.md similarity index 100% rename from spec-ui-hero.md rename to docs/design/spec-ui-hero.md diff --git a/spec-ui-layout.md b/docs/design/spec-ui-layout.md similarity index 100% rename from spec-ui-layout.md rename to docs/design/spec-ui-layout.md diff --git a/spec-ui-navigation.md b/docs/design/spec-ui-navigation.md similarity index 100% rename from spec-ui-navigation.md rename to docs/design/spec-ui-navigation.md diff --git a/spec-ui-project-detail.md b/docs/design/spec-ui-project-detail.md similarity index 100% rename from spec-ui-project-detail.md rename to docs/design/spec-ui-project-detail.md diff --git a/spec-ui-projects-list.md b/docs/design/spec-ui-projects-list.md similarity index 100% rename from spec-ui-projects-list.md rename to docs/design/spec-ui-projects-list.md diff --git a/spec-ui-projects.md b/docs/design/spec-ui-projects.md similarity index 100% rename from spec-ui-projects.md rename to docs/design/spec-ui-projects.md diff --git a/docs/design/spec-v2.md b/docs/design/spec-v2.md new file mode 100644 index 0000000..09ddf08 --- /dev/null +++ b/docs/design/spec-v2.md @@ -0,0 +1,441 @@ +# Specification — v2 Features + +> **Document:** `spec-v2.md` +> **Version:** 0.1.0 +> **Status:** Draft — awaiting review +> **Branch:** `dev_v2` +> **Parent branch:** `dev` (v0.0.1) + +--- + +## Overview + +Phase 1 (Foundation) + Phase 2 (Core Portfolio) đã hoàn thành trong v0.0.1. v2 tập trung vào: + +1. **Resume download** (P1) +2. **Blog system** — MDX-based articles (P1) +3. **SEO** — metadata, Open Graph, sitemap (P1) +4. **Analytics** — privacy-friendly page view tracking (P2) +5. **Testing** — Vitest + Testing Library (P5) +6. **CI/CD pipeline** (P5) + +--- + +## 1. Resume Download + +### Requirement + +- Nút "Download Resume" trong nav hoặc Contact page +- Link đến file PDF (placeholder ban đầu) +- Khi chưa có PDF → ẩn nút, hoặc hiển thị "Coming soon" +- PDF sẽ upload vào `public/resume.pdf` + +### Implementation + +```tsx +// Navigation.tsx +{resumeAvailable && ( + Resume +)} + +// OR ContactPage.tsx +Download Resume +``` + +### Data + +- `public/resume.pdf` — PDF file (user tự upload) +- Không cần data module + +### Acceptance + +- [ ] Nút Resume hiển thị trong nav +- [ ] Click → download PDF +- [ ] Khi chưa có PDF → nút ẩn hoặc disabled +- [ ] Responsive trên mobile + +--- + +## 2. Blog System + +### Requirement + +Blog cho phép viết technical articles bằng Markdown/MDX, render trên client. + +### Architecture + +``` +src/ + content/ + blog/ + post-1.mdx + post-2.mdx + components/ + blog/ + BlogListPage.tsx + BlogPostPage.tsx + ArticleCard.tsx + CodeBlock.tsx +``` + +### Features + +#### 2.1. Frontmatter + +Mỗi article có frontmatter: + +```yaml +--- +title: "Building High-Performance Event Simulation with Go" +date: "2024-06-15" +tags: ["engineering", "golang", "simulation"] +summary: "Discrete event simulation for logistics facilities" +--- +``` + +#### 2.2. Blog List Page (`/blog`) + +- Hiển thị danh sách articles +- Sort theo date (newest first) +- Filter theo tags (pill buttons) +- Mỗi article card: title, date, tags, summary + +#### 2.3. Article Page (`/blog/:slug`) + +- Render MDX content +- Code blocks với syntax highlighting +- TOC (table of contents) sidebar (desktop) +- Reading time estimate +- Breadcrumb navigation + +#### 2.4. Code Highlighting + +- Dùng `rehype-prism-plus` hoặc `rehype-raw` + `prismjs` +- Không dùng library nặng như `react-syntax-highlighter` +- Theme: dark/light compatible với CSS variables + +#### 2.5. MDX Processing + +- Dùng `@mdx-js/react` + `@mdx-js/rollup` (Vite plugin) +- Build-time compilation (không runtime) +- Frontmatter extracted tại build time + +### Vite Config Changes + +```ts +// vite.config.ts +import mdx from '@mdx-js/rollup' + +export default defineConfig({ + plugins: [ + react(), + mdx({ + providerImportSource: '@mdx-js/react', + }), + ], +}) +``` + +### Acceptance + +- [ ] `/blog` hiển thị danh sách articles +- [ ] Article card có title, date, tags, summary +- [ ] Click article → navigate đến `/blog/:slug` +- [ ] MDX content render đúng +- [ ] Code blocks có syntax highlighting +- [ ] Tags filter hoạt động +- [ ] TOC sidebar (desktop only) +- [ ] Reading time hiển thị +- [ ] Responsive +- [ ] Không crash khi missing article + +--- + +## 3. SEO + +### Requirement + +Mỗi page có metadata riêng cho SEO và social sharing. + +### Implementation + +#### 3.1. Dynamic Metadata + +Dùng `react-helmet-async` (hoặc `@remix-run/react` helmet nếu cần SSR sau này). + +```tsx +import { Helmet } from 'react-helmet-async' + +// HomePage.tsx + + {profile.name} — Senior Software Engineer + + + +``` + +#### 3.2. Open Graph + +Mỗi page có OG tags: + +```html + + + + + +``` + +#### 3.3. Sitemap + +- Generate `sitemap.xml` tại build time +- Dùng `vite-plugin-sitemap` hoặc tự viết script +- Include tất cả public pages + +#### 3.4. Robots.txt + +- `public/robots.txt` +- Allow all (trừ `/admin` nếu có sau này) + +#### 3.5. Structured Data (JSON-LD) + +- `Person` schema cho homepage +- `Article` schema cho blog posts +- `BreadcrumbList` cho nested pages + +### Acceptance + +- [ ] Mỗi page có `` và `<meta description>` riêng +- [ ] OG tags đúng trên mỗi page +- [ ] `sitemap.xml` generated tại build +- [ ] `robots.txt` có trong `public/` +- [ ] JSON-LD structured data +- [ ] Canonical URL đúng + +--- + +## 4. Analytics + +### Requirement + +Privacy-friendly analytics — không dùng Google Analytics. + +### Options + +**Option A: Plausible Analytics** (recommended) +- Lightweight, privacy-first +- No cookie banner needed +- Simple script integration + +**Option B: Umami** +- Self-hosted option +- Open source +- Similar to Plausible + +**Option C: Custom minimal tracking** +- Track page views only +- Store in localStorage +- Batch send to endpoint (optional) + +### Implementation (Plausible) + +```tsx +// main.tsx +<script + defer + data-domain="yourdomain.com" + src="https://plausible.io/js/script.outbound-links.js" +/> +``` + +Hoặc dùng `react-use-plausible`: + +```tsx +import { usePlausible } from 'react-use-plausible' + +const plausible = usePlausible() +// Auto pageview tracking +``` + +### Acceptance + +- [ ] Page view tracking hoạt động +- [ ] Không cookie banner +- [ ] Không ảnh hưởng performance +- [ ] Configurable via env var (ENABLE_ANALYTICS) + +--- + +## 5. Testing + +### Requirement + +Unit tests cho components và hooks. E2E tests cho critical paths. + +### Stack + +- **Vitest** — unit/integration tests +- **@testing-library/react** — component tests +- **@testing-library/jest-dom** — assertions +- **Playwright** — E2E tests + +### Test Structure + +``` +src/ + __tests__/ + hooks/ + useTheme.test.tsx + components/ + Navigation.test.tsx + Footer.test.tsx + Badge.test.tsx + pages/ + HomePage.test.tsx + e2e/ + navigation.spec.ts + theme.spec.ts + responsive.spec.ts +``` + +### Critical Tests + +#### useTheme + +```tsx +test('cycles through themes correctly', () => { + const { result } = renderHook(() => useTheme()) + act(() => { result.current.cycleTheme() }) + expect(result.current.theme).toBe('light') // or 'dark' +}) + +test('persists theme to localStorage', () => { + renderHook(() => useTheme()) + expect(localStorage.getItem('portfolio-theme')).toBe('dark') +}) +``` + +#### Navigation + +```tsx +test('renders all nav items', () => { + render(<Navigation />) + navItems.forEach(item => { + expect(screen.getByText(item.label)).toBeInTheDocument() + }) +}) + +test('NavLink highlights active route', () => { + render(<MemoryRouter initialEntries={['/about']}> <Navigation /> </MemoryRouter>) + expect(screen.getByText('About')).toHaveClass('active') +}) +``` + +#### HomePage + +```tsx +test('renders hero section', () => { + render(<HomePage />) + expect(screen.getByRole('heading', { name: profile.name })).toBeInTheDocument() +}) +``` + +### Acceptance + +- [ ] useTheme tests pass +- [ ] Navigation tests pass +- [ ] HomePage tests pass +- [ ] E2E: navigation works +- [ ] E2E: theme toggle works +- [ ] E2E: responsive layout correct +- [ ] Test coverage > 70% + +--- + +## 6. CI/CD Pipeline + +### Requirement + +GitHub Actions pipeline: + +1. **Lint** — oxlint +2. **Type check** — tsc -b +3. **Test** — vitest +4. **Build** — vite build +5. **Deploy** — to Vercel (on main branch push) + +### GitHub Actions + +```yaml +# .github/workflows/ci.yml +name: CI + +on: + push: + branches: [dev, main] + pull_request: + branches: [dev] + +jobs: + ci: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: pnpm + - run: pnpm install --frozen-lockfile + - run: pnpm lint + - run: pnpm build + - run: pnpm test +``` + +### Vercel Integration + +- Connect GitHub repo +- Auto deploy on `dev` → preview +- Auto deploy on `main` → production +- Environment variables: `SITE_URL`, `PLAUSIBLE_DOMAIN` (optional) + +### Acceptance + +- [ ] CI pass trên push vào dev +- [ ] Lint pass +- [ ] Build pass +- [ ] Tests pass +- [ ] Preview deploy trên Vercel +- [ ] Production deploy khi merge vào main + +--- + +## Implementation Order + +Ưu tiên thực hiện: + +1. **Resume download** (5 phút, trivial) +2. **SEO** (metadata, OG, sitemap) — cần làm trước khi deploy +3. **Blog system** (MDX + articles) — P1, substantial work +4. **Analytics** (Plausible) — quick win +5. **Testing** (Vitest + E2E) — P5, important but can iterate +6. **CI/CD** (GitHub Actions) — P5, automate after features done + +--- + +## Out of Scope (v2) + +- CMS integration (Phase 5+) +- Multi-language / i18n (Phase 5+) +- Interactive diagrams / simulations (Phase 5+) +- Search functionality (Phase 5+) +- Contact form with backend (Phase 5+) +- Resume PDF generation (user uploads manually) + +--- + +## Approval + +- [ ] All requirements reviewed and confirmed +- [ ] Implementation order agreed +- [ ] Ready to start coding diff --git a/spec.md b/docs/design/spec.md similarity index 100% rename from spec.md rename to docs/design/spec.md diff --git a/docs/design/spec_v1.md b/docs/design/spec_v1.md new file mode 100644 index 0000000..353e13b --- /dev/null +++ b/docs/design/spec_v1.md @@ -0,0 +1,174 @@ +# Specification — v1 (Foundation + Core Portfolio) + +> **Document:** `spec_v1.md` +> **Version:** 1.0.0 +> **Status:** Completed +> **Branch:** `dev` (merged from `dev_v1`) +> **Tag:** `v0.0.1` +> **Commit:** `7e42bd8` (feat) + `59951a7` (docs) + +--- + +## Overview + +v1 implements **Phase 1 (Foundation)** and **Phase 2 (Core Portfolio)** from `spec.md`. All pages, components, theming, and responsive layout are complete. + +--- + +## Completed Features + +### 1. Foundation + +| Feature | Status | Details | +|---------|--------|---------| +| Vite 8 + React 19 + TypeScript 6 | Done | Bundler mode, strict linting | +| Oxlint 1 | Done | `react/rules-of-hooks` error, `react/only-export-components` warn | +| React Router v6 | Done | Pin `6.30.6`, 7 routes defined | +| CSS Variables + Theming | Done | `data-theme` attribute, dark/light/system | +| Responsive Design | Done | Mobile menu, fluid containers, touch-friendly | + +### 2. Routing & Pages + +| Route | Page | Component | Status | +|-------|------|-----------|--------| +| `/` | Home | `HomePage` | Done | +| `/about` | About | `AboutPage` | Done | +| `/experience` | Experience | `ExperiencePage` | Done | +| `/projects` | Projects List | `ProjectsListPage` | Done | +| `/projects/:id` | Project Detail | `ProjectDetailPage` | Done | +| `/engineering` | Engineering | `EngineeringPage` | Done (placeholder content) | +| `/contact` | Contact | `ContactPage` | Done | + +### 3. Layout Components + +| Component | File | Status | +|-----------|------|--------| +| `Layout` | `src/components/layout/Layout.tsx` | Done — wraps Navigation + main + Footer | +| `Navigation` | `src/components/layout/Navigation.tsx` | Done — desktop menu, mobile drawer, theme toggle | +| `Footer` | `src/components/layout/Footer.tsx` | Done — copyright, nav links, social links | + +### 4. Page Sections (HomePage) + +| Section | Component | Status | +|---------|-----------|--------| +| Hero | `src/components/sections/Hero.tsx` | Done — name, title, tagline, CTA, social links | +| About | `src/components/sections/About.tsx` | Done — bio, engineering philosophy, current interests | +| Expertise | `src/components/sections/Expertise.tsx` | Done — skill groups grid | +| Experience | `src/components/sections/Experience.tsx` | Done — timeline with responsibilities | +| Projects | `src/components/sections/Projects.tsx` | Done — featured projects grid | +| Contact | `src/components/sections/Contact.tsx` | Done — email, GitHub, LinkedIn links | + +### 5. UI Components + +| Component | File | Props/Features | Status | +|-----------|------|----------------|--------| +| `Button` | `src/components/ui/Button.tsx` | `variant`, `size`, `disabled` | Done | +| `Badge` | `src/components/ui/Badge.tsx` | `variant: accent | outline | muted` | Done | +| `Tag` | `src/components/ui/Tag.tsx` | `accent` | Done | +| `Card` | `src/components/ui/Card.tsx` | `as`, children | Done | +| `SectionHeading` | `src/components/ui/SectionHeading.tsx` | `title`, `subtitle` | Done | +| `SocialLinks` | `src/components/ui/SocialLinks.tsx` | `links`, `variant` | Done | + +### 6. Theming + +| Feature | Status | Details | +|---------|--------|---------| +| `ThemeProvider` | Done | Context provider, `data-theme` on `<html>` | +| `useTheme()` hook | Done | Returns `{ theme, resolvedTheme, setTheme, cycleTheme }` | +| Theme cycle | Done | `dark` ↔ `light` ↔ `system` (system skips to opposite) | +| localStorage persistence | Done | Key: `portfolio-theme` | +| System preference detection | Done | `prefers-color-scheme: dark` | +| CSS variables for both themes | Done | `src/index.css` root + `[data-theme="dark"]` | + +### 7. Data Layer + +| Module | File | Content | Status | +|--------|------|---------|--------| +| Profile | `src/data/profile.ts` | Name, title, tagline, bio, links, interests, philosophy | Done | +| Skills | `src/data/skills.ts` | 6 skill groups × 5-6 skills each | Done | +| Experience | `src/data/experience.ts` | 1 entry with 3 featured achievements | Done | +| Projects | `src/data/projects.ts` | 4 projects with sections, metrics, tech stacks | Done | + +### 8. Types + +| Interface | File | Fields | Status | +|-----------|------|--------|--------| +| `Profile` | `src/types/index.ts` | name, title, tagline, bio, email, links, interests, philosophy | Done | +| `SkillGroup` | `src/types/index.ts` | title, skills[] | Done | +| `ExperienceEntry` | `src/types/index.ts` | id, title, company, duration, location, responsibilities, achievements | Done | +| `FeaturedAchievement` | `src/types/index.ts` | id, title, context, technicalWork, impact, metrics, technologies, featured | Done | +| `Project` | `src/types/index.ts` | id, title, summary, category, role, technologies, metrics, featured, urls | Done | +| `ProjectDetail` | `src/types/index.ts` | extends Project + sections[] | Done | +| `ProjectSection` | `src/types/index.ts` | id, number, title, content, type | Done | +| `PhilosophyPoint` | `src/types/index.ts` | title, description, keywords[] | Done | +| `ProjectCategory` | `src/types/index.ts` | 6 union types | Done | + +--- + +## Architecture + +``` +App.tsx + └── ThemeProvider + └── BrowserRouter + └── Layout + ├── Navigation (top bar + mobile drawer) + ├── <Routes> + │ ├── HomePage (Hero + About + Expertise + Experience + Projects + Contact) + │ ├── AboutPage + │ ├── ExperiencePage + │ ├── ProjectsListPage + │ ├── ProjectDetailPage + │ ├── EngineeringPage + │ └── ContactPage + └── Footer +``` + +**Data flow:** All content comes from `src/data/*.ts` modules. Components are presentational — no hardcoded text except labels/CTAs. + +**CSS:** Global variables in `src/index.css`, component styles in `src/App.css`. No CSS library. + +--- + +## Known Limitations + +| # | Limitation | Impact | v2 Plan | +|---|------------|--------|---------| +| 1 | No Blog system | Cannot publish articles | Phase 4: MDX-based blog | +| 2 | No SEO metadata | No `<title>`, `<meta>`, OG tags per page | Phase 5: react-helmet-async | +| 3 | No Analytics | No page view tracking | Phase 5: Plausible | +| 4 | No Testing | No unit/E2E tests | Phase 5: Vitest + Playwright | +| 5 | No CI/CD | Manual builds only | Phase 5: GitHub Actions | +| 6 | No Resume download | No PDF resume | v2: Add link/button | +| 7 | Engineering page placeholder | "Coming soon" text | v2: Populate with real content | +| 8 | Projects use `<a href>` not `<Link>` | Client-side nav broken on projects page | v2: Fix to `<Link>` | +| 9 | No i18n | Vietnamese-only | Future: English support | +| 10 | No CMS | Content in TS files | Future: headless CMS or MDX | + +--- + +## Files Summary + +| Category | Count | Path | +|----------|-------|------| +| Pages | 7 | `src/pages/*.tsx` | +| Layout components | 3 | `src/components/layout/*.tsx` | +| Section components | 6 | `src/components/sections/*.tsx` | +| UI components | 6 | `src/components/ui/*.tsx` | +| Data modules | 4 | `src/data/*.ts` | +| Hooks | 1 | `src/hooks/useTheme.tsx` | +| Types | 1 | `src/types/index.ts` | +| CSS | 2 | `src/index.css`, `src/App.css` | +| **Total source files** | **30** | | + +--- + +## Approval + +- [x] All Phase 1 + Phase 2 requirements implemented +- [x] TypeScript compiles without errors +- [x] Oxlint passes +- [x] Build succeeds +- [x] Responsive on mobile/desktop +- [x] Tagged `v0.0.1` on branch `dev` +- [x] AGENTS.md updated with project context