# Execution Plan — frontend-shell ## Detailed Analysis Summary ### Transformation Scope (Brownfield) - **Transformation Type**: Single package (`web/`), application-level changes only — no architectural or infrastructure transformation - **Primary Changes**: Complete the application shell: footer, back-to-top, skip link + main landmark, 404 and error pages, logo link, full navigation with placeholder routes, scroll restoration, shared site content module, theme additions for reused styling, test toolchain, security headers on dev/preview server, tech-debt clean-up - **Related Components**: `AppShell`, `NavigationBar` (+ `navItems`), `Footer`, `Hero` (socials source), `theme.ts`, `main.tsx` (router options), `routes/*`, `vite.config.js`, `package.json` ### Change Impact Assessment - **User-facing changes**: Yes — new footer, to-top button, skip link, 404/error pages, extra menu items and placeholder pages, footer contrast deviates from design (AA) - **Structural changes**: Yes (minor) — new shell components, shared `siteContent` module, shared router-link primitive; shell stays Header / main / Footer - **Data model changes**: Yes (minor) — new typed `SiteContent` shape; `HeroContent.socials` moves to it - **API changes**: No external API. Internal: Hero's content props change (socials no longer in `heroContent`) - **NFR impact**: Yes — accessibility (WCAG 2.1 AA), new test toolchain incl. PBT, security headers / CSP, supply-chain hygiene ### Component Relationships ```mermaid graph TD Root["routes/__root.tsx"] --> AppShell["AppShell"] Root --> NotFound["NotFound page (new)"] Root --> ErrorPage["Error page (new)"] AppShell --> SkipLink["SkipLink (new)"] AppShell --> Nav["NavigationBar (changed)"] AppShell --> Main["main#main + Outlet (new)"] AppShell --> Footer["Footer (rebuilt)"] AppShell --> ToTop["BackToTop (new)"] Nav --> NavItems["navItems (changed)"] Footer --> SiteContent["siteContent (new)"] Hero["Hero (changed)"] --> SiteContent Footer --> Theme["theme.ts (changed)"] ToTop --> Theme Main --> Pages["placeholder routes (new)"] classDef existing fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; classDef changed fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; classDef added fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; class Root,AppShell existing; class Nav,NavItems,Hero,Theme,Footer changed; class NotFound,ErrorPage,SkipLink,Main,ToTop,SiteContent,Pages added; ``` Text alternative: the root route renders AppShell plus new NotFound/Error pages; AppShell gains SkipLink, a main landmark, a rebuilt Footer and a new BackToTop; Footer and Hero both read the new siteContent module; theme.ts is extended (blue = unchanged, yellow = changed, green = new). - **Primary Component**: `web/` (React SPA) — Change Type: Minor (additive), Priority: Critical - **Infrastructure Components**: none (only `vite.config.js` dev/preview headers — Configuration-only) - **Shared Components**: `theme.ts`, `siteContent`, shared router-link primitive — Minor - **Dependent Components**: `Hero` (socials source) — Minor - **Supporting Components**: new test setup (Vitest config, test utils, generators) — Minor ### Risk Assessment - **Risk Level**: Low — isolated front-end, not deployed yet, every change reversible via git - **Rollback Complexity**: Easy - **Testing Complexity**: Moderate — new toolchain (Vitest + RTL + fast-check) and jsdom limits around scrolling/media queries ## Workflow Visualization ```mermaid flowchart TD Start(["User Request"]) subgraph INCEPTION["🔵 INCEPTION PHASE"] WD["Workspace Detection
COMPLETED"] RE["Reverse Engineering
COMPLETED"] 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"] NFRA["NFR Requirements
EXECUTE"] NFRD["NFR Design
SKIP"] ID["Infrastructure Design
SKIP"] CG["Code Generation
(Planning + Generation)
EXECUTE"] BT["Build and Test
EXECUTE"] end Start --> WD WD --> RE RE --> RA RA -.-> US RA --> WP WP --> AD AD -.-> UG AD --> FD FD --> NFRA NFRA -.-> NFRD NFRA -.-> ID NFRA --> CG CG --> BT BT --> End(["Complete
(Operations: ask again)"]) style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff style RE 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 NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,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 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 Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000 style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000 linkStyle default stroke:#333,stroke-width:2px ``` Text alternative: completed Inception stages (green) lead to Application Design, Functional Design and NFR Requirements (orange, execute), then Code Generation and Build and Test (green); User Stories, Units Generation, NFR Design and Infrastructure Design are skipped (grey). The Operations phase is undecided and will be asked again after Build and Test. ## Phases to Execute ### 🔵 INCEPTION PHASE - [x] Workspace Detection (COMPLETED) - [x] Reverse Engineering (COMPLETED) - [x] Requirements Analysis (COMPLETED) - [x] User Stories (SKIPPED) - **Rationale**: One persona (site visitor), requirements already concrete per shell element with clear acceptance; stories would restate FR-01…FR-11 - [x] Execution Plan (IN PROGRESS) - [ ] Application Design - EXECUTE (minimal depth) - **Rationale**: Several new components (Footer, BackToTop, SkipLink, NotFound, ErrorPage, placeholder page layout) and new shared pieces (`siteContent`, shared router-link primitive, theme additions such as a subtle-link style). Their boundaries, props and what gets centralised in the theme (NFR-02 reuse principle) should be decided once, before code - [ ] Units Generation - SKIP - **Rationale**: One package, one cohesive unit ("frontend-shell"); no parallel streams or deployment boundaries to split on ### 🟢 CONSTRUCTION PHASE - [ ] Functional Design - EXECUTE (minimal depth) - **Rationale**: Required by PBT-01 — identify testable properties of the shell's logic (to-top visibility threshold, footer/nav item derivation, current-year copyright, content shape). Also pins down the `SiteContent` data model and to-top / skip-link behaviour rules - [ ] NFR Requirements - EXECUTE (minimal depth) - **Rationale**: Tech stack decisions for the new test toolchain (Vitest, RTL, jsdom, fast-check — PBT-09), accessibility acceptance criteria, exact security header set and CSP (SECURITY-04), supply-chain checks (SECURITY-10) - [ ] NFR Design - SKIP - **Rationale**: The NFR patterns are small and concrete (one header config in `vite.config.js`, one Vitest setup, one generators file); they are specified directly in NFR Requirements and the code generation plan without a separate design document - [ ] Infrastructure Design - SKIP - **Rationale**: No infrastructure; hosting is out of scope (Operations undecided). Production header requirements are documented, not provisioned - [ ] Code Generation - EXECUTE (ALWAYS) - **Rationale**: Implementation planning and code generation needed - [ ] Build and Test - EXECUTE (ALWAYS) - **Rationale**: Build, test (incl. PBT with seed logging) and verification needed ### 🟡 OPERATIONS PHASE - [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - UNDECIDED - **Rationale**: Operations Configuration = Undecided (Q14 = C); asked again at Build and Test ## Package Change Sequence Single package (`web/`). Suggested order inside the unit (detailed in the code generation plan): 1. Test toolchain + tech-debt clean-up (safe base, `pnpm build` green) 2. Theme additions + shared primitives (`siteContent`, shared router link) 3. Routes + `navItems` (placeholder pages, privacy page) 4. Shell components (SkipLink + main, Footer, BackToTop, logo link) 5. 404 + error pages, scroll restoration 6. Security headers on dev/preview server 7. Tests (example-based + property-based) per step, final full run ## Estimated Timeline - **Total Stages Remaining**: 5 (Application Design, Functional Design, NFR Requirements, Code Generation, Build and Test) - **Estimated Duration**: a few working sessions; each design stage is short (minimal depth), Code Generation is the bulk ## Success Criteria - **Primary Goal**: Every page renders inside a complete shell matching LAYOUT.md and the static design (minus the side area and mobile e-mail), with the agreed accessibility and contrast adjustments - **Key Deliverables**: - Footer, BackToTop, SkipLink + main landmark, logo link, full navigation - Placeholder routes `/portfolio`, `/soorten-fotoshoots`, `/contact`, `/privacyverklaring` - 404 and generic error pages inside the shell; scroll restoration - `siteContent` module used by Hero and Footer; reused/centralised styling per NFR-02 - Vitest + RTL + fast-check setup with example-based and property-based tests - Security headers on dev/preview server + documented production header set - Tech-debt items from FR-11 resolved - **Quality Gates**: - `pnpm build` succeeds (type-check + bundle) - `pnpm test` passes, PBT seed logged on failure - `pnpm audit` reviewed, no unaddressed high/critical issues - Security Baseline and PBT compliance summaries have no blocking findings - Manual keyboard/screen check of the shell (skip link, focus styles, to-top, menus) - **Integration Testing**: Shell + routes together (navigation, 404, error boundary, scroll restoration) - **Operational Readiness**: Out of scope unless Operations is chosen at Build and Test