# Execution Plan — contact-forms-module ## Detailed Analysis Summary ### Transformation Scope - **Transformation Type**: Multiple components (new module + targeted changes in existing ones). No infrastructure/deployment model change. - **Primary Changes**: new `Modules.Contact` (+ Tests); `category` on `Modules.Offerings`; `OnRejected` and a public-route marker in Core/Availability; later mail integration (Core/Email) and admin UI (frontend). - **Related Components**: Core (rate limiting, hosting, observability), Modules.Availability (middleware), Modules.Offerings, Api.SlpSoftware (+ Api.AndreaSlopFotografie after the ASF merge), frontend (admin). ### Change Impact Assessment - **User-facing changes**: Yes: public contact endpoints (consumed by `cms-client`), admin "Berichten" screen (unit 6). - **Structural changes**: Yes: one new module, one new marker attribute in Core. - **Data model changes**: Yes: new tables (`ContactMessage`, idempotency record, DataProtection key ring), new `Offering.Category` column. All additive. - **API changes**: Yes: new endpoints + `category` on offerings; 429 body/header change on existing rate-limited endpoints. - **NFR impact**: Yes: security baseline (anonymous PII endpoint), privacy (retention, logging), reliability (mail retry). ### Component Relationships ```mermaid flowchart LR FE["cms-client (SLP site)"] --> API["Api.SlpSoftware / Api.AndreaSlopFotografie"] API --> CONTACT["Modules.Contact (NEW)"] API --> OFF["Modules.Offerings (+category)"] API --> AVAIL["Modules.Availability (middleware)"] CONTACT --> CORE["Core (marker, rate limiter, observability)"] AVAIL --> CORE CONTACT -. "after ASF merge" .-> MAIL["Core/Email (ASF branch)"] ADMIN["frontend admin: Berichten"] -. "after ASF merge" .-> CONTACT classDef new fill:#9ae6b4,stroke:#2f855a,color:#000; classDef changed fill:#f6e05e,stroke:#c05621,color:#000; classDef ext fill:#bee3f8,stroke:#2b6cb0,color:#000; classDef later fill:#e2e8f0,stroke:#4a5568,stroke-dasharray: 5 5,color:#000; class CONTACT new; class OFF,AVAIL,CORE,API changed; class FE ext; class MAIL,ADMIN later; ``` Text alternative: the Contact module (new, green) hangs off the API hosts and uses Core; Offerings, Availability, Core and the hosts change (yellow); mail and the admin UI (grey, dashed) wait for the ASF merge. ### Risk Assessment - **Risk Level**: Medium (anonymous endpoint with PII; shared files with the ASF session). - **Rollback Complexity**: Easy to Moderate (additive migrations; new module can be left unregistered per host). - **Testing Complexity**: Moderate (gate regression, rate limiter behaviour, token/idempotency, background jobs). ## Workflow Visualization ```mermaid flowchart TD Start(["Request via Redesign - SLS"]) subgraph INCEPTION["🔵 INCEPTION"] WD["Workspace Detection
COMPLETED"] RE["Reverse Engineering
SKIP (targeted review)"] RA["Requirements Analysis
COMPLETED"] US["User Stories
SKIP"] WP["Workflow Planning
IN PROGRESS"] AD["Application Design
EXECUTE (minimal)"] UG["Units Generation
EXECUTE"] end subgraph CONSTRUCTION["🟢 CONSTRUCTION (per unit)"] FD["Functional Design
EXECUTE (U3, U4, U5)"] NFR["NFR Requirements + Design
EXECUTE (U2, U3)"] ID["Infrastructure Design
SKIP (config noted in design)"] CG["Code Generation
EXECUTE"] BT["Build and Test
EXECUTE"] end OPS["Operations
UNDECIDED (at Build and Test)"] Start --> WD --> RA --> WP --> AD --> UG --> FD --> NFR --> CG --> BT --> OPS 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 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 NFR 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 ID fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style OPS fill:#FFF59D,stroke:#F9A825,stroke-width:2px,stroke-dasharray: 5 5,color:#000 style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 linkStyle default stroke:#333,stroke-width:2px ``` Text alternative: Inception runs Application Design and Units Generation, then each unit goes through design (where needed), Code Generation and Build and Test; Operations is undecided. ## Phases to Execute ### 🔵 INCEPTION - [x] Workspace Detection (COMPLETED) - [x] Reverse Engineering (SKIPPED by D10: targeted review recorded in requirements) - [x] Requirements Analysis (COMPLETED, approved by Redesign - SLS) - [x] User Stories (SKIPPED: contract-driven backend work; acceptance criteria live in the contract and the SLS requirements FR-13..19) - [ ] Workflow Planning (IN PROGRESS) - [ ] Application Design - EXECUTE (minimal depth) - **Rationale**: new module, new Core marker attribute; must fix component/service names, config keys (`Offerings:Categories`, `Contact:*`, `RateLimiting:ContactForm`), OpenAPI export path, DataProtection key-ring storage, purpose strings. - [ ] Units Generation - EXECUTE - **Rationale**: six units with an ordering constraint and a split at the ASF merge. ### 🟢 CONSTRUCTION - [ ] Functional Design - EXECUTE for U3, U4, U5 (validation rules, state/status machine, idempotency, spam cap, retry/backoff); SKIP for U1, U2, U6 (covered by contract/design) - [ ] NFR Requirements + NFR Design - EXECUTE for U2 and U3 (security baseline: PII logging, token oracle, size limits, rate limiting); SKIP for the others (covered by baseline checks in code generation) - [ ] Infrastructure Design - SKIP (no new infrastructure; key-ring storage and config keys are recorded in Application Design) - [ ] Code Generation - EXECUTE per unit (plan approved by Redesign - SLS before any code); automatic build+test per unit - [ ] Build and Test - EXECUTE (after U1-U4, again after U5-U6) ### 🟡 OPERATIONS - [ ] UNDECIDED: resolved at Build and Test (D7) ## Units (execution order) Phase 1: now, on the master base. Phase 2: only after Bryan merges `feature/identity-email-notifications` and the branch is rebased (not before; no rebase now). | Unit | Scope | Delivers | Tests | Depends on | |---|---|---|---|---| | **U1 offerings-category** (a) | `Category` on Offering entity, public + admin DTOs, create/update requests; validation against `Offerings:Categories` (per host appsettings); null/empty allowed | additive migration `AddOfferingCategory` in Offerings; config key documented; handoff note for the frontend (field name and semantics) | Offerings.Tests: mapping, validation (in list / not in list / null), repository; migration builds | none | | **U2 gate-and-limiter** (b) | `OnRejected`: `429 application/problem+json` + `Retry-After` for all policies; `[PublicSiteEndpoint]` marker in Core; `AvailabilityMiddleware` lets marked endpoints through (deny-by-default); mark `GET /api/v1/offerings`. Minimal diffs in these two files (R3) | marker attribute, middleware check, updated 429 response, security-event kept | Core.Tests/Api.Tests: 429 body + header for existing policies (adjust existing tests); Availability.Tests: marked route open while disabled/maintenance/master-down; **every `/api/v1/admin/*` route still 503**; `/api/v1/Availability/status` open; ~6-10 existing tests touched | none (U1 for the offerings route mark) | | **U3 contact-core** (c) | new `Modules.Contact` (+Tests): entities `ContactMessage`, `IdempotencyRecord`; DbContext + migration; token endpoint (DataProtection, per-site purpose, persistent key ring in DB); submit endpoint (validation codes, 413 ProblemDetails, `Idempotency-Key`, honeypot `hpCheck`, min-time, `ICaptchaVerifier` + Null, identical 202, spam stored with daily cap and 30-day retention, site id from config); `ContactForm` rate-limit policies; both routes `[PublicSiteEndpoint]`; `IContactMailSender` interface with no-op implementation (mail is wired in U5); retention `BackgroundService`; log/Sentry scrubbing for the routes | module registered in Api.SlpSoftware (Andrea host later), additive migration `InitialCreate`, config section `Contact:*`, exported OpenAPI document (path fixed in design) | Contact.Tests: validation rules incl. PBT (partial: round-trips, trim/length invariants), token sign/verify/expiry/foreign-site, idempotency replay, spam paths identical response, spam cap, retention job, no-PII-in-log test, endpoint tests via WebApplicationFactory | U2 | | **U4 contact-admin-api** (e) | AdminOnly endpoints: list (paging, unread count, spam separate), detail, PATCH status (new/read/archived), DELETE (hard), `POST resend` (rate-limited; calls `IContactMailSender`, so a no-op until U5); capabilities entry is automatic from the module name | admin controller + DTOs, OpenAPI updated | Contact.Tests: authorization (non-admin 403/401), paging, counts exclude spam, status transitions, hard delete, resend rate-limit | U3 | | **U5 contact-mail** (d) | PHASE 2. Implement `IContactMailSender` on `Core/Email` with a **new `MailKind`**, dark-mode contrast kept; From/Reply-To rules, header-injection and HTML-encoding protections; `mailStatus`/`mailAttempts`; `BackgroundService` sweeping `pending` (minutes) and retrying `failed` with backoff/max attempts; "no SMTP host = store only + admin notice" | mail path + retry job; Andrea host registration via env-only addresses | Contact.Tests: sender with fake `IEmailSender`, retry/backoff, header injection, encoding, failure never fails the request | merge of ASF branch + rebase; U3, U4 | | **U6 admin-ui** (f) | PHASE 2. "Berichten" in `frontend/`: list+paging+unread count, detail, status, delete, mail status + resend; menu entry via capabilities; only new files + menu entry | UI + tests | frontend unit tests (Vitest as in repo) | merge of ASF branch + rebase; U4 | ## Migration Approach - Contact and Offerings have their **own DbContext and migration history**, applied with `Database.Migrate()` at startup (D8). All migrations are additive (new tables, one nullable column). - ASF changes live in `Core/Migrations` and the Identity/Availability contexts, so snapshot conflicts with U1/U3 are not expected. If the rebase still produces conflicts in any snapshot, delete and regenerate my own migration after the rebase (R2). - DataProtection key ring: table owned by the Contact module's context (persistent per host; per-site purpose string). ## Branch and Process - Worktree `..\SlpModularCms-contact-forms`, branch `feature/contact-forms-module` from master `d9cc539`. The main checkout is never switched. - One commit per unit minimum; no push, merge or PR without explicit instruction. Per unit: Code Generation plan -> approval by Redesign - SLS -> code + automatic build+test -> status message. - Stage status reports to Redesign - SLS after each stage; contract deviations reported immediately. ## Estimated Timeline - **Total units**: 6 (4 now, 2 after the ASF merge). Rough effort: U1 small, U2 small-medium, U3 large, U4 medium, U5 medium, U6 medium. No calendar estimate (depends on approval turnaround and the ASF merge). ## Success Criteria - **Primary Goal**: contract v0.3.1 implemented on the CMS side without breaking ASF-owned behaviour. - **Key Deliverables**: category on offerings; public contact endpoints; admin API; mail + retry; admin UI; exported OpenAPI. - **Quality Gates**: per-unit build+test green; Security Baseline checked per stage; no PII in logs (tested); `/api/v1/admin/*` stays gated (tested); no ASF addresses in committed config.