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>
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;
Revealand 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 checkand 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