# Execution Plan - identity-email-notifications ## Detailed analysis - **Request type**: New feature across shared Core, Identity and the admin frontend. - **Risk**: Medium-high. It handles SMTP credentials, links that grant account access, an anonymous endpoint, and three additive database changes that run on every host (SlpSoftware included). - **Depth**: Comprehensive. **Extensions**: Security Baseline (enforced), PBT partial (PBT-02, 03, 07, 08, 09). **Operations**: yes. - **Lane**: Feature. ## Stages | Stage | Run? | Reason | |---|---|---| | Workspace Detection | done | | | Reverse Engineering | skip | shared artifacts reused | | Requirements Analysis | done (approval pending) | | | User Stories | skip | one user type (administrators, plus the person who resets a password); acceptance criteria are in requirements.md | | Workflow Planning | this document | | | Application Design | run | new components (sender, templates, settings store, reset flow) | | Units Generation | run | three units with clear dependencies | | Functional Design | per unit, where noted below | mail rules, reset rules, language fallback | | NFR Requirements / NFR Design | per unit, light | security-driven (tokens, anonymity, timeouts) | | Infrastructure Design | U1 only | config keys, env secrets on the Pi, smtp4dev, SPF/DKIM alignment | | Code Generation | each unit | per-unit build and test | | Build and Test | once at the end | | | Operations | yes | deployment config, monitoring, production-readiness incl. SPF alignment | ## Units and order ```mermaid flowchart LR U1["U1 mail-foundation
sender, options, templates,
SiteSettings + Mail card"] --> U2["U2 identity-mail-flows
language per user, invitation,
new link, resend, notices"] U2 --> U3["U3 password-reset
forgot/reset, cooldown,
session revocation on completion"] classDef u fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; class U1,U2,U3 u; ``` Text alternative: U1 (foundation) is built first, then U2 (flows that use it and the language column), then U3 (password reset, which needs both). | Unit | Scope | Migration | |---|---|---| | U1 mail-foundation | `IEmailSender` + `SmtpEmailSender`, `EmailOptions` + start-up validation, template renderer + resources (nl, en), `SiteSettings` store + service + API + Mail card, `emailEnabled` and `defaultLanguage` in system capabilities, fake sender, smtp4dev docs | new table `SiteSettings` | | U2 identity-mail-flows | `PreferredLanguage` on users, `Language` on invitations, profile language select, invite dialog language and mail result, invitation / new-link / resend mails, deactivation, reactivation and role-change notices, resend action in the users list | columns `Users.PreferredLanguage`, `Invitations.Language` (nullable) | | U3 password-reset | `forgot-password` / `reset-password`, Identity token provider, cooldown, revocation of refresh tokens on completion only, access-token stamp check (decision D2), login link and two pages | none (token provider is stateless) | All three migrations are additive, nullable (or new tables), with a working `Down`, and safe to run on SlpSoftware's database. ## Approval and delivery gates - Requirements and this design go to Bryan through "CMS & API" before any code (his rule for this feature). - Each unit is built and tested (per-unit build and test), hand-back after each unit. - Branch `feature/identity-email-notifications`; push and deploy to ASF test only with the relayed permission pattern used so far (branch push, `deploy_asf_test`; no merge, no SLP Software, no production). - A real test mail to an address of Bryan from the test host is part of acceptance (Operations). ## Success criteria Mail disabled = behaviour unchanged (all existing tests green). Mail enabled = every mail kind sent correctly with a fake sender; failures never fail an action; reset request never touches password or sessions; completed reset revokes them; sender address only from the allowlist; no secrets in logs or messages.