Files
AndreaSlopFotografie/aidlc-docs/features/frontend-shell/inception/plans/execution-plan.md
T
SluijsensandClaude Opus 5.5 db2fa89b90 Adds AI-DLC inception docs for the front-end shell feature
Workspace detection, reverse engineering of web/, requirements with
answered verification questions, the execution plan and the open
application design questions for the frontend-shell feature.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-14 13:03:26 +02:00

11 KiB

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

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

flowchart TD
    Start(["User Request"])

    subgraph INCEPTION["🔵 INCEPTION PHASE"]
        WD["Workspace Detection<br/><b>COMPLETED</b>"]
        RE["Reverse Engineering<br/><b>COMPLETED</b>"]
        RA["Requirements Analysis<br/><b>COMPLETED</b>"]
        US["User Stories<br/><b>SKIP</b>"]
        WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
        AD["Application Design<br/><b>EXECUTE</b>"]
        UG["Units Generation<br/><b>SKIP</b>"]
    end

    subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
        FD["Functional Design<br/><b>EXECUTE</b>"]
        NFRA["NFR Requirements<br/><b>EXECUTE</b>"]
        NFRD["NFR Design<br/><b>SKIP</b>"]
        ID["Infrastructure Design<br/><b>SKIP</b>"]
        CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
        BT["Build and Test<br/><b>EXECUTE</b>"]
    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<br/>(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

  • Workspace Detection (COMPLETED)
  • Reverse Engineering (COMPLETED)
  • Requirements Analysis (COMPLETED)
  • User Stories (SKIPPED)
    • Rationale: One persona (site visitor), requirements already concrete per shell element with clear acceptance; stories would restate FR-01…FR-11
  • 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