# 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; 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