Requirements, application design (incl. concept-API-contract voor het contactformulier), units en functional design voor U1. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
163 lines
10 KiB
Markdown
163 lines
10 KiB
Markdown
# Execution Plan — redesign-modern-timetravel
|
||
|
||
## Detailed Analysis Summary
|
||
|
||
### Transformation Scope (Brownfield Only)
|
||
- **Transformation Type**: Multi-component application change (frontend re-theme + new capability) with a cross-repo dependency (CMS/API).
|
||
- **Primary Changes**: Replace the red/purple dark theme with variant (B/E) × mode (light/dark); rebuild all landing sections to design B; build variant E (five eras) as a lazy-loaded alternative; generic packages block with filter and mobile swipe row; contact form with headless module.
|
||
- **Related Components**: this repo (`slp-software-frontend`); SlpModularCms (endpoint, `category` field, headless form package); consumer sites such as AndreaSlopFotografie (own `ContactForm` today).
|
||
|
||
### Change Impact Assessment
|
||
- **User-facing changes**: Yes — complete visual redesign, new variant switch, new form, new mobile packages UX.
|
||
- **Structural changes**: Yes — theme model, route/variant composition with lazy E bundle, new form module boundary.
|
||
- **Data model changes**: Yes — `PackageCardData.category`; new contact message entity (CMS side).
|
||
- **API changes**: Yes — new `POST /api/v1/contact-messages`; extended `GET /api/v1/offerings`.
|
||
- **NFR impact**: Yes — security (PII, spam, rate limiting), accessibility (WCAG AA, reduced motion), performance (code split, fonts).
|
||
|
||
### Component Relationships
|
||
```mermaid
|
||
graph TD
|
||
FE[slp-software-frontend - PRIMARY, major] --> API[SlpModularCms API - endpoint and category, major]
|
||
FE --> Mod[Headless form package - from SlpModularCms, major]
|
||
Mod --> API
|
||
Andrea[AndreaSlopFotografie and other sites - consumers, later] --> Mod
|
||
FE --> Nginx[nginx proxy and CSP - config only]
|
||
classDef primary fill:#63b3ed,stroke:#2b6cb0,color:#000;
|
||
classDef ext fill:#f6e05e,stroke:#c05621,color:#000;
|
||
classDef cfg fill:#9ae6b4,stroke:#2f855a,color:#000;
|
||
class FE primary;
|
||
class API,Mod,Andrea ext;
|
||
class Nginx cfg;
|
||
```
|
||
Text alternative: the frontend depends on the CMS API and on the headless form package that the CMS repo ships; other sites consume the same package; nginx and CSP need configuration changes.
|
||
|
||
| Component | Change type | Reason | Priority |
|
||
|---|---|---|---|
|
||
| slp-software-frontend | Major | redesign, theme model, form UI | Critical |
|
||
| SlpModularCms API | Major | contact endpoint, `category` | Critical (form), Important (category) |
|
||
| Headless form package (SlpModularCms) | Major | agreed reusable module | Critical (for form unit) |
|
||
| nginx / CSP | Configuration-only | API route, fonts | Important |
|
||
| Other sites (Andrea etc.) | Minor, later | adopt module | Optional (out of this feature) |
|
||
|
||
### Risk Assessment
|
||
- **Risk Level**: Medium-High (large visual scope, cross-repo contract, PII handling)
|
||
- **Rollback Complexity**: Easy for the frontend (branch/PR revert, hash-routed static bundle); Moderate for CMS endpoint (data stored)
|
||
- **Testing Complexity**: Complex (themes × variants × viewports, form states, cross-repo contract)
|
||
|
||
## Workflow Visualization
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Start(["User Request"])
|
||
|
||
subgraph INCEPTION["🔵 INCEPTION PHASE"]
|
||
WD["Workspace Detection<br/><b>COMPLETED</b>"]
|
||
RE["Reverse Engineering<br/><b>COMPLETED</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>EXECUTE</b>"]
|
||
end
|
||
|
||
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE (per unit U1..U5)"]
|
||
FD["Functional Design<br/><b>EXECUTE U1 U3 U4</b>"]
|
||
NFRA["NFR Requirements<br/><b>EXECUTE U4 U5</b>"]
|
||
NFRD["NFR Design<br/><b>EXECUTE U4 U5</b>"]
|
||
ID["Infrastructure Design<br/><b>EXECUTE U4</b>"]
|
||
CG["Code Generation<br/><b>EXECUTE</b>"]
|
||
BT["Build and Test<br/><b>EXECUTE</b>"]
|
||
end
|
||
|
||
OPS["Operations Phase<br/><b>UNDECIDED - asked after Construction</b>"]
|
||
|
||
Start --> WD --> RE --> RA
|
||
RA -.-> US
|
||
RA --> WP --> AD --> UG --> FD
|
||
FD --> NFRA --> NFRD --> ID --> CG
|
||
CG -.->|next unit| FD
|
||
CG --> BT
|
||
BT -.-> OPS
|
||
BT --> End(["Complete"])
|
||
|
||
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||
style RE 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 US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||
style UG 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 NFRA fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||
style NFRD 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 OPS fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||
style INCEPTION fill:#BBDEFB,stroke:#1565C0,stroke-width:3px,color:#000
|
||
style CONSTRUCTION fill:#C8E6C9,stroke:#2E7D32,stroke-width:3px,color:#000
|
||
linkStyle default stroke:#333,stroke-width:2px
|
||
```
|
||
|
||
Text alternative: inception runs Application Design and Units Generation (User Stories skipped), then construction loops over five units with design stages only where useful; Operations is decided after construction.
|
||
|
||
## Phases to Execute
|
||
|
||
### 🔵 INCEPTION PHASE
|
||
- [x] Workspace Detection (COMPLETED)
|
||
- [x] Reverse Engineering (COMPLETED)
|
||
- [x] Requirements Analysis (COMPLETED)
|
||
- [x] User Stories (SKIP) — single visitor persona, requirements already detailed; can be added on request
|
||
- [~] Workflow Planning (IN PROGRESS)
|
||
- [ ] Application Design — EXECUTE
|
||
- **Rationale**: new components and boundaries: variant/mode theme model, lazy E bundle composition, packages block (grid/filter/swipe), headless form module and its API contract with the CMS. The **form contract** produced here is what the CMS session and other form sessions can start from.
|
||
- [ ] Units Generation — EXECUTE
|
||
- **Rationale**: multiple units with different risk and dependency (see below).
|
||
|
||
### 🟢 CONSTRUCTION PHASE
|
||
Units (proposed order, B first as requested):
|
||
- **U1 theme-foundation**: variant × mode model, tokens (B light/dark, E tokens placeholder), system preference, nav switch buttons (mode + icon-only variant button), removal of red/purple, fonts.
|
||
- **U2 b-modern-sections**: hero, Over (photo), Werkwijze, nav/footer, contact block frame, light/dark.
|
||
- **U3 packages-block**: generic grid, skeleton, filter chips (4+), swipe row on mobile, `category` field, B styling.
|
||
- **U4 contact-form**: headless form logic + validation + states, B styling, contract with CMS, spam fields, privacy line. **Coordination gate**: the user is notified before this unit's design/implementation starts (see below).
|
||
- **U5 e-timetravel**: lazy-loaded E with five eras, Win98 Werkwijze step cards, packages (2006 style) and form styling per era, light/dark, reduced-motion handling.
|
||
|
||
Stage decisions:
|
||
- [ ] Functional Design — EXECUTE for U1, U3, U4; SKIP for U2, U5 (design exists in the canvas)
|
||
- **Rationale**: U1 theme state rules, U3 filter/swipe behaviour, U4 form states/validation/contract are real logic; U2/U5 are visual ports of the canvas.
|
||
- [ ] NFR Requirements — EXECUTE for U4, U5; SKIP for U1-U3
|
||
- **Rationale**: U4 security/PII/rate-limit/spam; U5 performance (code split, effects) and accessibility with heavy effects. Other units covered by requirements.md NFR-1..8.
|
||
- [ ] NFR Design — EXECUTE for U4, U5 (follows NFR Requirements)
|
||
- [ ] Infrastructure Design — EXECUTE for U4 only (lightweight)
|
||
- **Rationale**: nginx route for the form endpoint, CSP/connect-src, env configuration; skipped for U1-U3 and U5 (no infra impact).
|
||
- [ ] Code Generation — EXECUTE (ALWAYS), per unit, with automatic per-unit build/test
|
||
- [ ] Build and Test — EXECUTE (ALWAYS)
|
||
|
||
### 🟡 OPERATIONS PHASE
|
||
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation — UNDECIDED
|
||
- **Rationale**: Requirements Q15-C; asked again at Build and Test.
|
||
|
||
## Package Change Sequence / Module Update Strategy
|
||
- **Update Approach**: Hybrid — frontend units sequential; CMS work parallel to U1-U3 once the contract exists.
|
||
- **Critical Path**: Application Design (form contract) → CMS endpoint + headless package → U4 integration.
|
||
- **Coordination Points**: `POST /api/v1/contact-messages` contract; `category` on `GET /api/v1/offerings`; headless package API (hook/component slots); nginx route and CSP.
|
||
- **Testing Checkpoints**: per-unit tests; contract test (mock server) for U4; integrated check once the CMS endpoint exists.
|
||
- **Rollback**: frontend by PR revert; CMS endpoint behind the agreed contract version; mailto fallback while the endpoint is unavailable (feature flag).
|
||
|
||
## Coordination Plan
|
||
- **Form notice (user request)**: the user is told **before the form unit starts**, so they can attach the CMS session and the sessions of other sites that want a form. Because the headless module comes from the CMS repo, the recommended moment is the end of **Application Design** (contract ready, CMS can start in parallel with U1-U3).
|
||
- Candidate sessions to attach (from the session list, to be chosen by the user): `CMS & API`, `slpmodularcms-ec`, `slpmodularcms-f7`, `slpmodularcms-6b`, `AndreaSlopFotografie`, `slpsoftware-5d`.
|
||
|
||
## Estimated Timeline
|
||
- **Total Phases**: 2 active (Inception remaining 2 stages; Construction 5 units), Operations undecided
|
||
- **Estimated Duration**: several working sessions; U5 is the largest unit.
|
||
|
||
## Success Criteria
|
||
- **Primary Goal**: B live as default site with working light/dark and an icon button revealing E; contact form working end-to-end.
|
||
- **Key Deliverables**: variant/mode theme system, B sections, generic packages block with mobile swipe row, contact form + contract + CMS hand-off, E variant, tests.
|
||
- **Quality Gates**: `pnpm lint`, `tsc -b`, `vitest run` green; WCAG AA checks; security baseline rules compliant; reduced-motion verified; contract test passing.
|
||
- **Integration Testing**: frontend ↔ CMS endpoint once available.
|
||
- **Operational Readiness**: decided at Build and Test (Operations undecided).
|