Files
AndreaSlopFotografie/aidlc-docs/features/contact-page/inception/plans/execution-plan.md
T
SluijsensandClaude Opus 5.5 9127eba776 Plans the Contact page and records unit 1 as generated
Workspace detection, a reverse engineering delta, requirements with the
approved layout mockups, the execution plan and the application design
for the Contact page, plus the code generation plan and summary of the
webPage helper. Corrects the contact payload in the shared API notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 08:50:48 +01:00

171 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Execution Plan — Contact Page
## Detailed Analysis Summary
### Transformation Scope (Brownfield)
- **Transformation Type**: Single component (`web/`), application-level only
- **Primary Changes**: replace the `/contact` placeholder with the real page (layout proposal 1a); extract the homepage contact form wiring into a shared `ContactPanel`; a new shared `ContactDetails` card; a privacy line and one reply-time value shared by both forms; a generic `webPage()` structured-data helper (consumed by two parallel features); page SEO (indexing, title/description, `ContactPage` JSON-LD, own preview image); Over mij links to `/contact`
- **Related Components**: `web/src/routes/contact.tsx`, `web/src/components/{ContactForm,home/ContactSection}`, new `ContactPanel` and `ContactDetails`, `web/src/content/` (`siteContent`, new contact content, `aboutContent`), `web/src/seo.ts`, `web/src/sitePages.ts`, `web/lighthouserc*.cjs`, `web/public/`, `web/src/assets/`, [LAYOUT.md](../../../../../LAYOUT.md)
### Change Impact Assessment
- **User-facing changes**: Yes — a new page; the homepage contact section gains the privacy line and must otherwise look and behave exactly as before; two Over mij links change target
- **Structural changes**: Minor — two shared components extracted/added; no architectural change
- **Data model changes**: Yes (small) — new contact page content interface; a reply-time value in `SiteContent`
- **API changes**: No external API. Internal: `webPage()` + `WebPageType` become a shared contract for portfolio-page and soorten-fotoshoots-page; `/contact?pakket=<packageId>` becomes a URL contract for soorten-fotoshoots-page
- **NFR impact**: Yes — SEO (indexed, structured data), accessibility (heading outline with a visually hidden h2, icon list), performance (form loads with the page; the large photo is the LCP on wide screens and must not load on phones)
### Component Relationships
```mermaid
graph TD
Route["routes/contact.tsx (new page)"] --> PageIntro["PageIntro (existing)"]
Route --> PageSection["PageSection (existing)"]
Route --> Panel["ContactPanel (new, extracted)"]
Route --> Details["ContactDetails (new)"]
Route --> Content["content: contact page content (new)"]
Route --> Seo["seo.ts: webPage + ContactPage (new)"]
HomeContact["home/ContactSection"] --> Panel
Panel --> Gate["ContactFormGate (existing)"]
Panel --> Form["ContactForm (privacy line, reply time)"]
Details --> SiteContent["siteContent (reply time added)"]
Form --> SiteContent
Seo --> AboutPage["aboutPage (rebuilt on webPage)"]
Seo --> Peers["portfolio-page and soorten-fotoshoots-page"]
AboutContent["aboutContent: links to /contact"] --> Route
classDef newpart fill:#FFA726,stroke:#E65100,stroke-width:1px,color:#000;
classDef changed fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
classDef existing fill:#e2e8f0,stroke:#4a5568,stroke-width:1px,color:#000;
classDef peer fill:#CE93D8,stroke:#6A1B9A,stroke-width:1px,color:#000;
class Route,Panel,Details,Content,Seo newpart;
class HomeContact,Form,SiteContent,AboutPage,AboutContent changed;
class PageIntro,PageSection,Gate existing;
class Peers peer;
```
Text alternative: the new contact route composes the existing PageIntro and PageSection with the new ContactPanel and ContactDetails, new content and the new webPage-based structured data; the homepage contact section switches to ContactPanel; the form gains the privacy line and the shared reply time; aboutPage is rebuilt on webPage, which the two parallel features also use; Over mij content links to the new page.
- **Primary Component**: `web` (front-end SPA)
- **Shared Components**: `seo.ts` (Minor, new `webPage()`; `aboutPage()` output unchanged), `ContactPanel` (new, used by the homepage), `ContactForm` (Minor: privacy line, reply time from content), `ContactDetails` (new)
- **Dependent Components**: homepage `ContactSection`; Over mij content; portfolio-page and soorten-fotoshoots-page (consume `webPage()` and the `?pakket=` contract)
- **Supporting Components**: Lighthouse CI config (Configuration-only), LAYOUT.md (documentation)
### Coordination with Parallel Features
- **Critical path for others**: unit 1 (`webPage()`) — portfolio-page and soorten-fotoshoots-page cherry-pick its commit; hash sent to both sessions right after it is committed.
- **Incoming**: soorten-fotoshoots-page commits `siteContent.serviceArea` + `professionalService()` changes in `seo.ts`; whoever commits second rebases. No functional dependency for this page (the description text is static in `sitePages.ts`).
- **Hot files**: own entries only in `sitePages.ts`, `lighthouserc*.cjs`, `active-features.md`.
### Risk Assessment
- **Risk Level**: Low to medium — the `ContactPanel` extraction touches the most intricate homepage section (lazy loading, `?pakket=` clean-up, focus, scroll); everything else is additive
- **Rollback Complexity**: Easy (one branch, commits per unit; unit 1 independent)
- **Testing Complexity**: Moderate — existing `ContactSection`, `ContactForm` and route tests guard the homepage behaviour; new tests for the page, the card, the URL parameter and the responsive photo; Lighthouse for `/contact`
## 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>SKIP</b>"]
end
subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
FD["Functional Design<br/><b>EXECUTE (units 2 and 3)</b>"]
NFRA["NFR Requirements<br/><b>SKIP</b>"]
NFRD["NFR Design<br/><b>SKIP</b>"]
ID["Infrastructure Design<br/><b>SKIP</b>"]
CG["Code Generation<br/>(Planning + Generation)<br/><b>EXECUTE</b>"]
BT["Build and Test<br/><b>EXECUTE</b>"]
end
Start --> WD
WD --> RE
RE --> RA
RA --> WP
WP --> AD
AD --> FD
FD --> CG
CG --> BT
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 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 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 ID 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: completed Workspace Detection, Reverse Engineering and Requirements Analysis lead to Workflow Planning, then Application Design, Functional Design (units 2 and 3), Code Generation per unit and Build and Test; User Stories, Units Generation, NFR Requirements, NFR Design, Infrastructure Design and the Operations phase are skipped.
## Phases to Execute
### 🔵 INCEPTION PHASE
- [x] Workspace Detection (COMPLETED)
- [x] Reverse Engineering (COMPLETED — delta)
- [x] Requirements Analysis (COMPLETED)
- [x] User Stories (SKIPPED)
- **Rationale**: one persona (the visitor), concrete FRs with texts, targets and an approved mockup
- [x] Execution Plan (IN PROGRESS)
- [ ] Application Design - EXECUTE (minimal depth)
- **Rationale**: new shared components and a shared contract need agreed boundaries before code: `webPage()` signature and its properties (already announced to two sessions), `ContactPanel` (what moves out of `ContactSection`, lazy vs eager), `ContactDetails` (props, data source, label per channel), where the privacy line and the reply time live, and the content interface for the page
- [ ] Units Generation - SKIP
- **Rationale**: the split is fixed below (three units); no separate unit-of-work artifacts needed
### 🟢 CONSTRUCTION PHASE
- [ ] Functional Design - EXECUTE for units 2 and 3 (minimal depth)
- **Rationale**: unit 2 has rules worth pinning down before code (which homepage behaviour `ContactPanel` must keep, which channels the card shows and with what label, PBT properties per PBT-01); unit 3 has the `?pakket=` handling on this page (clean-up without focus move), the responsive photo rule (LCP on wide screens, not downloaded on phones) and the content model. Unit 1 is a small pure helper whose properties are set in Application Design
- [ ] NFR Requirements - SKIP
- **Rationale**: NFRs are set at requirements level (NFR-CP-01..06) and the stack is fixed
- [ ] NFR Design - SKIP
- **Rationale**: no new NFR patterns; the responsive-photo approach is decided in Functional Design of unit 3; existing patterns (DeferredImage, Reveal, jsonLdScript, focus ring) are reused
- [ ] Infrastructure Design - SKIP
- **Rationale**: static assets only; no server config, CSP or deployment changes
- [ ] Code Generation - EXECUTE (ALWAYS, per unit)
- **Rationale**: implementation and tests
- [ ] Build and Test - EXECUTE (ALWAYS)
- **Rationale**: full `pnpm check` incl. Lighthouse for `/`, `/over-mij` and `/contact`
### 🟡 OPERATIONS PHASE
- [ ] Deployment Setup, Monitoring Setup, Production Readiness Validation - SKIP
- **Rationale**: Operations Configuration = No; the existing pipeline deploys to test on merge
## Units of Work (in order)
| # | Unit | Scope | Requirements |
|---|---|---|---|
| 1 | **webPage helper** | `webPage()` + `WebPageType` in `seo.ts`; `aboutPage()` rebuilt on it with identical output; example and property tests. Only `seo.ts` and `seo.test.ts`. One commit; hash sent to portfolio-page and soorten-fotoshoots-page. | SEO-CP-03 (helper part) |
| 2 | **Shared contact blocks** | Extract `ContactPanel` from `ContactSection` (homepage unchanged apart from the privacy line); privacy line under the form; reply time as one `siteContent` value used by the thank-you message; new `ContactDetails` card (icons, valid channels only). | FR-CP-02 (shared parts), FR-CP-04, FR-CP-06, FR-CP-07, FR-CP-08, NFR-CP-02 |
| 3 | **Contact page** | Photos (original resized, small portrait crop, 1200×630 preview) with alt texts; page content + types; the route with layout 1a and the narrow-screen card; `?pakket=` preselect; SEO (indexed, title/description, `ogImage`, `ContactPage` JSON-LD, Lighthouse indexed paths); Over mij links to `/contact`; LAYOUT.md. | FR-CP-01..05, FR-CP-09..11, SEO-CP-01..05, NFR-CP-01, 03..06 |
Unit 1 goes first because two other features wait for it and it is independent of the rest. Unit 2 before unit 3 because the page builds on its components. Each unit: one or more commits on `feature/contact-page`, full `pnpm check` (incl. Lighthouse) before its completion message; one PR to master at the end.
## Estimated Timeline
- **Total Stages to execute from here**: 6 (Application Design, Functional Design ×2 units, Code Generation ×3 units, Build and Test)
- **Estimated Duration**: two working sessions
## Success Criteria
- **Primary Goal**: a finished, indexed Contact page in the approved layout, reusing the homepage form
- **Key Deliverables**: `/contact` page; `webPage()` (shared with two features); `ContactPanel`, `ContactDetails`, privacy line, shared reply time; contact content; resized photos, portrait crop and preview image; updated Over mij links, LAYOUT.md and Lighthouse config
- **Quality Gates**: `pnpm check` passes (lint, format, tests with coverage thresholds, build, audits, Lighthouse: accessibility 1.0, best practices 1.0, performance ≥ 0.9 for `/contact`, homepage and Over mij budgets unchanged); axe clean; homepage contact section unchanged in behaviour after unit 2; `aboutPage()` output unchanged after unit 1
- **Integration Testing**: route tests render `/`, `/over-mij` and `/contact` in the shell; `/contact?pakket=newborn` preselects Newborn and cleans the URL; Over mij links reach `/contact`