# 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 ```mermaid 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 ```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 1 and 2"] NFRA["NFR Requirements
SKIP"] NFRD["NFR Design
SKIP"] ID["Infrastructure Design
EXECUTE, unit 3"] CG["Code Generation
EXECUTE"] BT["Build and Test
EXECUTE"] 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 - [x] Workspace Detection (COMPLETED) - [x] Reverse Engineering (SKIPPED) - **Rationale**: Shared artifacts exist; team agreement is no full refresh per feature - [x] Requirements Analysis (COMPLETED) - [x] User Stories (SKIPPED) - **Rationale**: One visitor type; the requirements are concrete and testable - [x] 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