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

172 lines
9.6 KiB
Markdown

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