# 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