# Execution Plan — Portfolio Page ## Detailed Analysis Summary ### Transformation Scope (Brownfield) - **Transformation Type**: Single component (`web/`), application-level only - **Primary Changes**: replace the `/portfolio` placeholder with the real page; new shared gallery building blocks (masonry `PortfolioGrid`, `Lightbox`, a generic filter bar) with pure helpers in `lib/`; `InstagramGrid` moved to a shared component with its own content; page-specific SEO (indexing, `ImageGallery` JSON-LD via the shared `webPage()`, own preview image); 10 photos in two sizes - **Related Components**: `web/src/routes/portfolio.tsx`, `web/src/routes/index.tsx`, `web/src/components/{home/InstagramGrid → InstagramGrid, PortfolioGrid, Lightbox, filter bar}`, `web/src/lib/`, `web/src/content/` (+ `types.ts`), `web/src/seo.ts`, `web/src/sitePages.ts`, `web/lighthouserc*.cjs`, `web/src/theme.ts` (possibly a `zIndex` token), `web/src/test/arbitraries.ts`, `web/public/`, `web/src/assets/portfolio/`, [LAYOUT.md](../../../../../LAYOUT.md) ### Change Impact Assessment - **User-facing changes**: Yes — a new page with filters and a lightbox; the homepage Instagram block must look and behave exactly as before - **Structural changes**: Minor — one component moved, new shared components; no architectural change - **Data model changes**: Yes — new portfolio photo content (two image sizes, `ShootTypeId`), `InstagramContent` split from `HomeContent` - **API changes**: No external API; new URL search parameter `?shoot=` on `/portfolio`; internal props for the new components - **NFR impact**: Yes — SEO (indexed, structured data, preview image), accessibility (modal dialog, focus management, announcements), performance (photo-heavy page, Lighthouse budget 0.9 on mobile) ### Component Relationships ```mermaid graph TD Route["routes/portfolio.tsx"] --> PageIntro["PageIntro (existing)"] Route --> Filter["Filter bar (new, generic)"] Route --> Grid["PortfolioGrid (new, masonry)"] Grid --> Lightbox["Lightbox (new, Chakra Dialog)"] Grid --> Deferred["DeferredImage + Reveal (existing)"] Route --> Insta["InstagramGrid (moved to shared)"] Home["routes/index.tsx"] --> Insta Insta --> InstaContent["content/instagramContent.ts (new)"] Route --> PfContent["content/portfolioContent.ts (new)"] PfContent --> ShootTypes["content/shootTypes.ts (from soorten-fotoshoots)"] Filter --> Lib["lib/ helpers (new, pure)"] Grid --> Lib Lightbox --> Lib Route --> Seo["seo.ts webPage() (from contact-page) + sitePages.ts"] Seo --> Lhci["lighthouserc*.cjs (indexed paths)"] classDef newpart fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000; classDef changed fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef existing fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000; classDef peer fill:#CE93D8,stroke:#6A1B9A,stroke-width:1px,color:#000; class Route,Filter,Grid,Lightbox,InstaContent,PfContent,Lib newpart; class Insta,Home,Seo,Lhci changed; class PageIntro,Deferred existing; class ShootTypes peer; ``` Text alternative: the new route composes PageIntro, a generic filter bar, the new masonry PortfolioGrid (which opens the new Lightbox and reuses DeferredImage and Reveal) and the shared InstagramGrid (also used by the homepage, with its own content); portfolio content references the shoot types delivered by soorten-fotoshoots (purple); filter, grid and lightbox rely on new pure helpers in lib; SEO uses contact-page's webPage() and the Lighthouse config follows the page registry. - **Primary Component**: `web` (front-end SPA) - **Shared Components**: `InstagramGrid` (Minor: moved, content type split), `PortfolioGrid`, `Lightbox`, filter bar (new, generic), `lib/` (new helpers), `seo.ts` (Minor: gallery JSON-LD on top of `webPage()`) - **Dependent Components**: the homepage route (import path and content source of `InstagramGrid` only) - **Supporting Components**: Lighthouse CI config (Configuration-only), `theme.ts` (possibly one token), LAYOUT.md (documentation) - **Peer dependencies**: contact-page (`webPage()` commit), soorten-fotoshoots-page (`shootTypes.ts` commit) ### Risk Assessment - **Risk Level**: Medium — the lightbox (focus trap, inert background, swipe, preloading) and the row-order masonry are the most intricate UI in the site so far; two pieces come from parallel branches - **Rollback Complexity**: Easy (one branch, commits per unit) - **Testing Complexity**: Moderate — dialog behaviour in jsdom (focus, keys), URL state, stateful PBT for the lightbox; Lighthouse for a photo-heavy page ## Workflow Visualization ```mermaid flowchart TD Start(["User Request"]) subgraph INCEPTION["🔵 INCEPTION PHASE"] WD["Workspace Detection
COMPLETED"] RE["Reverse Engineering
SKIP"] RA["Requirements Analysis
COMPLETED"] US["User Stories
SKIP"] WP["Workflow Planning
IN PROGRESS"] AD["Application Design
EXECUTE"] UG["Units Generation
SKIP"] end subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"] FD["Functional Design
EXECUTE (units 2 and 3)"] NFRA["NFR Requirements
SKIP"] NFRD["NFR Design
SKIP"] ID["Infrastructure Design
SKIP"] CG["Code Generation
(Planning + Generation)
EXECUTE"] BT["Build and Test
EXECUTE"] end Start --> WD WD --> RA RA --> WP WP --> AD AD --> FD FD --> CG CG --> BT BT --> End(["Complete"]) style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style FD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style UG fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style NFRA fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style NFRD fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000 style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000 style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 linkStyle default stroke:#333,stroke-width:2px ``` Text alternative: completed Workspace Detection and Requirements Analysis lead to Workflow Planning, then Application Design, Functional Design (units 2 and 3), Code Generation per unit and Build and Test; Reverse Engineering, User Stories, Units Generation, NFR Requirements, NFR Design, Infrastructure Design and the Operations phase are skipped. ## Phases to Execute ### 🔵 INCEPTION PHASE - [x] Workspace Detection (COMPLETED) - [x] Reverse Engineering (SKIPPED) - **Rationale**: shared artifacts are current with the over-mij blocks; team agreement that each feature only updates the lines about its own route/components (done during Code Generation) - [x] Requirements Analysis (COMPLETED) - [x] User Stories (SKIPPED) - **Rationale**: one persona (the visitor); concrete FRs with behaviour, texts and edge cases; stories would restate the requirements - [x] Execution Plan (IN PROGRESS) - [ ] Application Design - EXECUTE (standard depth) - **Rationale**: several new shared components need agreed boundaries and props before code, generic enough for other pages: `PortfolioGrid`, `Lightbox`, the filter bar, the moved `InstagramGrid` and its content type, the portfolio content model (two image sizes, `ShootTypeId`), which pure helpers go into `lib/`, where URL state lives (route search params vs. component state), whether the hero's swipe logic is extracted, and how the peer commits slot in - [ ] Units Generation - SKIP - **Rationale**: the split is fixed below (three units); no separate unit-of-work artifacts needed ### 🟢 CONSTRUCTION PHASE - [ ] Functional Design - EXECUTE for units 2 and 3 (standard depth) - **Rationale**: unit 2 has real logic (filtering, wrap-around navigation, lightbox state machine, masonry spans, preloading) whose rules and properties must be defined first (PBT-01). Unit 3 has the photo proposals (shoot type and alt text per photo, to be approved by the user — clarification 4), the OG photo choice, the `?shoot=` parsing rules and the `ImageGallery` structured data rules. Unit 1 is a behaviour-preserving move with nothing to design beyond Application Design - [ ] NFR Requirements - SKIP - **Rationale**: NFRs are set at requirements level (NFR-PF-01..06) and the stack is fixed (no new dependencies) - [ ] NFR Design - SKIP - **Rationale**: no new NFR patterns beyond what Application/Functional Design covers; existing ones (DeferredImage, Reveal, theme focus ring, `jsonLdScript`, reduced motion) are reused - [ ] Infrastructure Design - SKIP - **Rationale**: static assets only; no server config, CSP or deployment changes - [ ] Code Generation - EXECUTE (ALWAYS, per unit) - **Rationale**: implementation and tests - [ ] Build and Test - EXECUTE (ALWAYS) - **Rationale**: full `pnpm check` incl. Lighthouse for `/` and `/portfolio`; browser check of the lightbox on desktop and phone ### 🟡 OPERATIONS PHASE - [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - SKIP - **Rationale**: Operations Configuration = No (decided at Requirements Analysis); the existing pipeline deploys to test on merge ## Units of Work (in order) | # | Unit | Scope | Requirements | Peer dependency | |---|---|---|---|---| | 1 | **Shared Instagram block** | Move `InstagramGrid` to `components/InstagramGrid/` with its own `InstagramContent` (`content/instagramContent.ts`); homepage switched over with unchanged output | FR-PF-08, NFR-PF-02 | none | | 2 | **Gallery building blocks** | Generic `PortfolioGrid` (row-order masonry, eager first N, link fallback), `Lightbox` (dialog, prev/next/wrap, keys, swipe, counter, caption, focus, preloading), generic filter bar; pure helpers in `lib/` with example and property-based tests; arbitraries; possibly a `zIndex` token and an extracted swipe hook. Tested with fixture data; not yet on a page | FR-PF-03, 05, 06, 07; NFR-PF-01..03, 05 | none | | 3 | **Portfolio page** | 10 photos (download, two sizes, alt texts and shoot types as approved), `portfolioContent.ts` + types; route with intro, filters wired to shoot types and `?shoot=`, grid, lightbox, Instagram; SEO (indexed, `ImageGallery` JSON-LD, `ogImage`, Lighthouse indexed paths); LAYOUT.md; RE lines about `/portfolio` and the new components | FR-PF-01, 02, 04, 09; SEO-PF-01..05; NFR-PF-04, 06 | `webPage()` (contact-page) and `shootTypes.ts` (soorten-fotoshoots), cherry-picked at the start of the unit | Units 1 and 2 have no peer dependency, so they can be built while the peers' commits are still pending. Unit 3 starts by cherry-picking both peer commits; if either is missing, it stops and reports (no parallel copy). Each unit: one or more commits on `feature/portfolio-page`, full `pnpm check` (incl. Lighthouse) before its completion message; one PR to master at the end. Whichever parallel feature merges first, the others rebase onto master; the hot files (`sitePages.ts`, `lighthouserc*.cjs`, `active-features.md`) only carry each feature's own entries. ## Estimated Timeline - **Total stages to execute from here**: 7 (Application Design, Functional Design ×2 units, Code Generation ×3 units, Build and Test) - **Estimated Duration**: two to three working sessions, plus waiting time on the two peer commits before unit 3 ## Success Criteria - **Primary Goal**: a finished, indexed portfolio page with filters and an accessible lightbox, matching the design, with the live photos - **Key Deliverables**: `/portfolio` page; shared `PortfolioGrid`, `Lightbox`, filter bar and `InstagramGrid`; `portfolioContent.ts` and `instagramContent.ts`; pure helpers with example and property-based tests; 10 photos in two sizes with approved alt texts and a 1200×630 preview image; updated LAYOUT.md, Lighthouse config and RE lines - **Quality Gates**: `pnpm check` passes (lint, format, tests with coverage thresholds, build, audits, Lighthouse: accessibility 1.0, best practices 1.0, SEO 1.0, performance ≥ 0.9 for `/portfolio`, homepage budgets unchanged); axe clean incl. the open lightbox; homepage output unchanged after unit 1 - **Integration Testing**: route tests render `/` and `/portfolio` in the shell; `/portfolio?shoot=` starts filtered and an invalid value falls back to "Alles"; the lightbox opens from the grid and returns focus; canonical URL has no parameters