Files
AndreaSlopFotografie/aidlc-docs/features/prerendering/inception/plans/execution-plan.md
T
SluijsensandClaude Opus 5.5 0c5d8b8f40 Compresses responses in the preview server
The baseline ran on vite preview, which compresses, so measurements could not
be compared without this. Also records that the real servers need compression.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 18:30:30 +01:00

9.6 KiB

Execution Plan

Detailed Analysis Summary

Transformation Scope

  • Transformation Type: Architectural, within one package (web/): from a client-rendered SPA to statically prerendered pages with hydration
  • Primary Changes: TanStack Start replaces the plain Vite entry; a post-build step moves inline scripts to files; Reveal and other display components work from prerendered HTML; nginx, IIS and CI handle the new output
  • Related Components: vite.config.ts, main.tsx, index.html, routes/__root.tsx, AppShell, NavigationBar/MobileNav, Reveal/useReveal, DeferredImage, NotFound, seo.ts, config/serverConfig.ts, deploy/, lighthouserc*.cjs, the CI workflow, the test setup

Change Impact Assessment

  • User-facing changes: Yes. Faster first paint, a changed fade-in at the top of pages, a mobile menu that works without JavaScript, a real 404
  • Structural changes: Yes. New app entry and root document, new build output, a new post-build step
  • Data model changes: No
  • API changes: No
  • NFR impact: Yes. Performance and SEO are the goal; the CSP must stay unchanged; the main bundle may grow

Component Relationships

graph TD
    Start["TanStack Start build"]
    Entry["App entry and root document"]
    Pages["Routes and shared components"]
    Extract["Post-build script step"]
    Config["serverConfig and deploy files"]
    CI["CI workflow and Lighthouse"]
    Hosts["nginx and IIS"]
    Start --> Entry
    Entry --> Pages
    Start --> Extract
    Extract --> CI
    Config --> Hosts
    CI --> Hosts
    classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef app fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    classDef infra fill:#fbd38d,stroke:#92400e,stroke-width:1px,color:#000;
    class Start,Extract core;
    class Entry,Pages app;
    class Config,CI,Hosts infra;

Text alternative: the Start build drives the app entry and pages and feeds the post-build step; its output goes through CI to nginx and IIS, which are configured from serverConfig.

Component Change type Reason Priority
Build, entry, root route Major Framework change Critical
Post-build script step (new) Major Keep the CSP unchanged Critical
Reveal, DeferredImage, MobileNav, breakpoint-dependent components Minor to major Prerendered HTML and working without JavaScript Important
serverConfig.ts, deploy/ Minor URLs and real 404 Critical
CI workflow, Lighthouse configuration Minor New output path, targets Critical
Test setup Minor Framework change Important

Risk Assessment

  • Risk Level: High. System-wide change with unknowns; the spike covered two simple pages only
  • Rollback Complexity: Moderate. All work is on one branch, and the deployed result is static, so an earlier release can be put back
  • Testing Complexity: Complex. Hydration, CSP and no-JavaScript behaviour need a real browser against the built output on two server types

Workflow Visualization

flowchart TD
    Start(["User Request"])

    subgraph INCEPTION["🔵 INCEPTION PHASE"]
        WD["Workspace Detection<br/><b>COMPLETED</b>"]
        RE["Reverse Engineering<br/><b>SKIP</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, units 1 and 2</b>"]
        NFRA["NFR Requirements<br/><b>SKIP</b>"]
        NFRD["NFR Design<br/><b>SKIP</b>"]
        ID["Infrastructure Design<br/><b>EXECUTE, unit 3</b>"]
        CG["Code Generation<br/><b>EXECUTE</b>"]
        BT["Build and Test<br/><b>EXECUTE</b>"]
    end

    Start --> WD
    WD --> RA
    RA --> WP
    WP --> AD
    AD --> FD
    FD --> ID
    ID --> 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 ID 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 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: after Workflow Planning come Application Design, Functional Design (units 1 and 2), Infrastructure Design (unit 3), Code Generation and Build and Test; Reverse Engineering, User Stories, Units Generation and both NFR stages are skipped.

Phases to Execute

🔵 INCEPTION PHASE

  • Workspace Detection (COMPLETED)
  • Reverse Engineering (SKIPPED)
    • Rationale: Shared artifacts exist; team agreement is no full refresh per feature
  • Requirements Analysis (COMPLETED)
  • User Stories (SKIPPED)
    • Rationale: One visitor type; the requirements are concrete and testable
  • Execution Plan (IN PROGRESS)
  • Application Design - EXECUTE
    • Rationale: New entry, root document and post-build step; component responsibilities and open technical choices need settling before code
  • Units Planning / Units Generation - SKIP
    • Rationale: The three units below follow from the dependencies and are fixed in this plan

🟢 CONSTRUCTION PHASE

  • Functional Design - EXECUTE for units 1 and 2, SKIP for unit 3
    • Rationale: Script extraction rules and fade-in, no-JavaScript and hydration behaviour need exact definitions and testable properties (PBT-01). Unit 3's logic is covered by Infrastructure Design; it records its properties there
  • NFR Requirements - SKIP
    • Rationale: The NFRs are in requirements.md and the stack is decided. PBT-09: fast-check is already a project dependency
  • NFR Design - SKIP
    • Rationale: NFR Requirements is skipped; script loading and measurement are settled in Application Design
  • Infrastructure Design - EXECUTE for unit 3
    • Rationale: Server rules for URLs and 404 on nginx and IIS, deployed output and upload order change
  • Code Generation - EXECUTE (ALWAYS)
    • Rationale: Implementation planning and code generation needed
  • Build and Test - EXECUTE (ALWAYS)
    • Rationale: Build, test and verification needed, including the human task on the Pi

🟡 OPERATIONS PHASE

  • Deployment Setup, Monitoring Setup, Production Readiness Validation - SKIP
    • Rationale: Operations Configuration = No. Necessary server and CI changes are part of unit 3

Units of Work

Unit Content Requirements Depends on
1. Start migration and script step Start setup, entry and root document, head tags, post-build script step and guard, hydration of all pages, Sentry and Umami, tests, CI output path and preview FR-PR-01 to 08, 19, 20, 22; catch-all route of FR-PR-14 and 15; NFR-PR-P-03, P-04, S-02, SEC-01 to 04, Q-01 to 05 None
2. Fade-in, no JavaScript, first photo Reveal, DeferredImage, mobile menu without JavaScript, carousels and form fallback, photo preload FR-PR-09 to 13, 21 Unit 1
3. Hosting and targets URLs without a redirect, real 404, nginx and IIS configuration, upload order, Lighthouse targets FR-PR-14 to 18, 23; NFR-PR-P-01, P-02, S-01 Units 1 and 2

Decision gate after unit 1 (NFR-PR-P-03): bundle size and Lighthouse scores are measured against master and shown to the owner. If they got worse, the owner decides whether to continue with Start before units 2 and 3 start.

Package Change Sequence

Single package (web/). Units run in sequence; unit 3 sets the final Lighthouse targets, so it comes last.

Estimated Timeline

  • Total Stages Remaining: 5 (Application Design, Functional Design, Infrastructure Design, Code Generation, Build and Test)
  • Estimated Duration: No fixed estimate. Each push to the pull request starts a full CI run of about 20 minutes on the Pi

Success Criteria

  • Primary Goal: All pages arrive as complete HTML, with better first paint and full crawlable content, under the unchanged CSP
  • Key Deliverables: Start-based build, post-build script step with guard, adjusted components, updated server configuration and CI, new Lighthouse targets
  • Quality Gates: pnpm check and CI pass; browser test of hydration under the production CSP; no-JavaScript content test; owner decisions recorded for any page below 0.9
  • Integration Testing: Built output tested on nginx (test environment) and against the IIS configuration
  • Operational Readiness: Monitoring keeps working (FR-PR-08); no new monitoring is added