Adds the prerendering requirements, design and baseline
Records the requirements, execution plan, application design, the first unit's functional design and code generation plan, and the baseline on master. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,23 @@
|
||||
# Application Design Plan: prerendering
|
||||
|
||||
Depth: standard. No question file was created: each open choice was settled by testing it in a spike or is purely technical, and the owner's decisions are in requirements.md. The design states its decisions and the consequences the owner should know. Business rules follow in Functional Design (units 1 and 2) and Infrastructure Design (unit 3).
|
||||
|
||||
## Plan
|
||||
|
||||
- [x] Analyse context
|
||||
- [x] Read requirements.md, execution-plan.md and the shared reverse-engineering artifacts
|
||||
- [x] Read in code: `main.tsx`, `__root.tsx`, `vite.config.ts`, `index.html`, `serverConfig.ts`, `securityHeaders.ts`, `lighthouserc.cjs`, the CI workflow, `Reveal`, `useReveal`, `useInView`, `DeferredImage`, `NavigationBar`, `MobileNav`, `NotFound`, `renderApp`
|
||||
- [x] Test the open technical choices in the spike
|
||||
- [x] Hydration under the production `script-src`, with inline and with moved scripts
|
||||
- [x] URLs without a trailing slash through `autoSubfolderIndex: false`
|
||||
- [x] Three ways to build the 404 page
|
||||
- [x] Search parameters during hydration
|
||||
- [x] Generate `components.md`
|
||||
- [x] Generate `component-methods.md`
|
||||
- [x] Generate `services.md`
|
||||
- [x] Generate `component-dependency.md`
|
||||
- [x] Generate `application-design.md`
|
||||
- [x] Validate design completeness and consistency
|
||||
- [x] Every FR-PR and NFR-PR item has a home in a unit
|
||||
- [x] Mermaid diagrams use `classDef` with `color:#000`, safe node ids and a text alternative
|
||||
- [x] Security Baseline and PBT compliance summarised; no blocking findings
|
||||
@@ -0,0 +1,171 @@
|
||||
# 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; 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
|
||||
Reference in New Issue
Block a user