Epic 10: Additional Stories

# Story 10.12: Self-Service Deregistration

Status: ready-for-dev Prerequisite: Story 10.11 (waitlist promotion must fire on cancellation)

User Story: As a registered attendee, I want to cancel my event registration easily without contacting an organizer — either by clicking a link in my confirmation email or by entering my email address on the event page — so that my spot can be given to someone else.

Background: Currently there is no self-service cancellation path. The Registration.status enum includes cancelled but no endpoint or UI supports transitioning to it from the attendee side. Organizers can manually cancel from the attendees tab but this requires contacting the organizer. The todo explicitly requests:

1. A non-expiring magic link embedded in the confirmation email
2. An email-input form on the public portal for deregistration

Scope:

Backend — Deregistration Token:

• Flyway V74: Add deregistration_token column to registrations (UUID, NOT NULL, unique — generated on creation, never rotated, never expires)
• RegistrationService.createRegistration() extended: generate UUID deregistration token and persist
• Migration backfill: UPDATE registrations SET deregistration_token = gen_random_uuid() WHERE deregistration_token IS NULL

Backend — Deregistration Endpoints:

# Public (no auth required — token IS the auth)
GET  /api/v1/registrations/deregister/verify?token={uuid}
     → 200: { registrationCode, eventCode, eventTitle, eventDate, attendeeFirstName }
     → 404: { error: "invalid_token" } (token not found or already cancelled)

POST /api/v1/registrations/deregister
     body: { token: uuid }
     → 200: success; fires waitlist promotion (Story 10.11)
     → 404: invalid token
     → 409: already cancelled

# Public (no auth required — email verification flow)
POST /api/v1/registrations/deregister/by-email
     body: { email: string, eventCode: string }
     → 200: always (anti-enumeration: "if registered, you'll receive a deregistration email")
     Sends email with deregistration link (containing token) if registration found

Email Template:

• deregistration-link-de.html + deregistration-link-en.html — content fragments with batbern-default layout
• Variables: recipientName, eventTitle, eventCode, eventDate, deregistrationLink
• deregistrationLink = {baseUrl}/deregister?token={deregistrationToken}
• Also embed deregistration link in the existing registration confirmation email: “To cancel: [Cancel Registration]”

Frontend — Deregistration Page (/deregister?token=):

• Public route (no auth required)
• Step 1 (token verify): shows event title, date, attendee name — “Are you sure you want to cancel your registration?”
• “Confirm Cancellation” button → POST /deregister → success state
• Invalid/used token → error state with contact info
• Already cancelled → “Your registration was already cancelled” state
• Component: DeregistrationPage.tsx (new public page, same pattern as UnsubscribePage.tsx)

Frontend — Deregistration via Email Form:

• On HomePage.tsx (when event is in AGENDA_PUBLISHED/AGENDA_FINALIZED/EVENT_LIVE state):
  • Secondary link “Cancel your registration” below registration CTA
  • Opens DeregistrationByEmailModal.tsx — email + eventCode input → submit → shows “Check your inbox” message
• On RegistrationWizard.tsx (when user is already registered — Story 10.10 guard):
  • “Cancel my registration” button alongside status display → opens same modal

Frontend — Organizer Attendees Tab:

• Cancelled registrations shown in table with grey CANCELLED chip
• Existing RegistrationActionsMenu already has cancel action for organizers — ensure it uses the same RegistrationService.cancelRegistration() that triggers waitlist promotion

Key new files:

services/event-management-service/src/main/resources/db/migration/V74__add_deregistration_token.sql
services/event-management-service/src/main/resources/email-templates/deregistration-link-de.html
services/event-management-service/src/main/resources/email-templates/deregistration-link-en.html
services/event-management-service/.../service/DeregistrationService.java
services/event-management-service/.../controller/DeregistrationController.java
services/event-management-service/.../service/DeregistrationServiceTest.java
services/event-management-service/.../controller/DeregistrationControllerIntegrationTest.java
web-frontend/src/pages/public/DeregistrationPage.tsx
web-frontend/src/components/public/DeregistrationByEmailModal.tsx
web-frontend/src/hooks/useDeregistration.ts

Key modified files:

docs/api/events.openapi.yml                                  — deregistration endpoints (FIRST)
services/event-management-service/.../domain/Registration.java — deregistrationToken field
services/event-management-service/.../service/RegistrationService.java — generate token on create; cancelRegistration() triggers waitlist promotion
services/event-management-service/.../service/RegistrationEmailService.java — add deregistrationLink variable to confirmation email
services/event-management-service/.../config/SecurityConfig.java — permitAll /deregister/** public paths
api-gateway/.../SecurityConfig.java                          — permitAll /api/v1/registrations/deregister/**
web-frontend/src/App.tsx                                     — /deregister public route
web-frontend/src/pages/public/HomePage.tsx                   — "Cancel registration" link
web-frontend/src/components/public/RegistrationWizard.tsx    — cancel button when already registered
public/locales/de/registration.json + en/registration.json   — deregistration.* keys

Definition of Done (Story 10.12):

• V74 migration runs cleanly; backfill generates tokens for all existing registrations
• TDD: DeregistrationServiceTest + DeregistrationControllerIntegrationTest TDD: `DeregistrationServiceTest` + `DeregistrationControllerIntegrationTest` written first
• Valid token → verify shows correct event/attendee info; confirm → status=cancelled; waitlist promotion fires (Story 10.11)
• Used/invalid token → 404; already cancelled → 409
• By-email flow: valid email → sends deregistration link email; unknown email → 200 (anti-enumeration, no email sent)
• Confirmation email (existing) includes deregistration link
• /deregister?token=valid `/deregister?token=valid` page renders correctly (no auth required)
• Organizer cancellation via attendees tab also triggers waitlist promotion
• Deregistration email templates seeded and editable in admin Email Templates tab
• OpenAPI spec committed before implementation (ADR-006)
• i18n: deregistration.* i18n: `deregistration.*` keys in de/en; Type-check passes; Checkstyle passes

# Story 10.13: Registration & Portal Email Templates — Editable in Admin

Status: ready-for-dev Prerequisite: Story 10.2 (Email Template Management — provides DB storage, seed service, admin UI)

User Story: As an organizer, I want the registration confirmation email and all speaker portal emails to be editable from the Email Templates admin tab — just like speaker invitation emails — so that I can update their subject and content without a code deploy.

Background: Story 10.2 seeded and made editable 22 classpath email templates (speaker invitations, task reminders, newsletter, etc.). However, two important categories were explicitly left out of the initial UI:

1. Registration emails: registration-confirmation-de/en.html (sent by RegistrationEmailService)
2. Speaker portal registration emails: Emails sent when a speaker creates their portal account or responds to an invitation via the portal (SpeakerAcceptanceEmailService, PortalRegistrationEmailService)

Additionally, organizers have requested a shortcut to jump directly to an event-relevant email template from the event page (e.g., “Edit Registration Template” from the event attendees tab) without navigating to the admin page manually.

Scope:

Backend — Seed Additional Templates:

• EmailTemplateSeedService.@PostConstruct extended to seed:
  • registration-confirmation-de/en (REGISTRATION category) — from existing classpath files
  • registration-waitlist-confirmation-de/en (REGISTRATION category) — from Story 10.11 files
  • deregistration-link-de/en (REGISTRATION category) — from Story 10.12 files
  • waitlist-promotion-de/en (REGISTRATION category) — from Story 10.11 files
  • portal-registration-de/en (SPEAKER category) — speaker portal account creation email
• All new templates: system templates (editable, not deletable)
• New REGISTRATION category added to EmailTemplateCategory enum (if not already present)

Frontend — Email Templates Tab Enhancement:

• EmailTemplatesTab.tsx: Add REGISTRATION category to the category filter (alongside Speaker, Task Reminders, Newsletter)
• Registration templates visible and editable in same TinyMCE editor as other content templates
• Preview merges with batbern-default layout and renders branded email preview

Frontend — Quick Template Access from Event Pages:

• EventParticipantsTab.tsx: “Edit Registration Email Template” icon-button (top-right) → opens EmailTemplateQuickEditDrawer.tsx with registration-confirmation-{locale} pre-loaded
• EventParticipantsTab.tsx: “Edit Waitlist Confirmation Email” icon-button → opens drawer with registration-waitlist-confirmation-{locale}
• EventParticipantsTab.tsx: “Edit Deregistration Email” icon-button → deregistration-link-{locale}
• EmailTemplateQuickEditDrawer.tsx: Right-side MUI Drawer (480px); embeds the same EmailTemplateEditModal content but without navigating away from the event page. Header shows “Email Template: [name]” + locale toggle + “Open in Admin” link

Key new files:

web-frontend/src/components/organizer/EventPage/EmailTemplateQuickEditDrawer.tsx

Key modified files:

services/event-management-service/.../service/EmailTemplateSeedService.java  — seed REGISTRATION category templates
services/event-management-service/.../domain/EmailTemplateCategory.java      — add REGISTRATION enum value
web-frontend/src/components/organizer/Admin/EmailTemplatesTab.tsx             — add REGISTRATION category filter
web-frontend/src/components/organizer/EventPage/EventParticipantsTab.tsx     — quick template access buttons
public/locales/de/organizer.json + en/organizer.json                          — emailTemplates.categories.registration key

Definition of Done (Story 10.13):

• All registration/portal email template classpath files are seeded to DB on service startup (idempotent)
• REGISTRATION category visible in Email Templates tab filter — all seeded templates listed and editable
• TinyMCE editor opens for registration templates; preview shows branded email with batbern-default layout
• Quick-edit drawer opens from EventParticipantsTab without navigating away; changes reflect immediately in admin tab
• Existing RegistrationEmailService Existing `RegistrationEmailService` loads templates from DB with classpath fallback (same pattern as other email services)
• Waitlist and deregistration email templates (Stories 10.11, 10.12) also editable via same tab
• i18n: emailTemplates.categories.registration i18n: `emailTemplates.categories.registration` key in de/en; Type-check passes

# Story 10.14: Newsletter Sending with Template Selection

Status: ready-for-dev Prerequisite: Story 10.2 (email template management), Story 10.7 (newsletter sending infrastructure)

User Story: As an organizer, I want to choose which email template to use when sending a newsletter for an event, so that I can use different templates for different types of communications (general newsletter, event reminder, partner announcement) without needing separate template hardcoding.

Background: Story 10.7 implemented newsletter sending from the EventNewsletterTab with a single hardcoded template key (newsletter-event-{locale}). The admin EmailTemplatesTab (Story 10.2) supports multiple templates in the NEWSLETTER category, but the newsletter sending UI doesn’t let organizers pick which one to use — it always uses the hardcoded default. This story adds template selection to the newsletter send flow.

Scope:

Backend — Newsletter Send API Extension:

• POST /api/v1/events/{eventCode}/newsletter/send request body extended with optional templateKey: string
  • If templateKey is provided → use that template from DB
  • If omitted → use default newsletter-event-{locale} (backward compatible)
• NewsletterEmailService.sendNewsletter() updated to accept templateKey parameter
• POST /api/v1/events/{eventCode}/newsletter/preview same extension for preview

Backend — Newsletter Template Listing:

• GET /api/v1/email-templates?category=NEWSLETTER — already works via existing EmailTemplateController (no changes needed)

Frontend — EventNewsletterTab:

• Before “Send Newsletter” and “Send Reminder” buttons: add a “Template” select dropdown
  • Populated by GET /api/v1/email-templates?category=NEWSLETTER response
  • Default selection: newsletter-event-{currentLocale} (same as current hardcoded behavior)
  • Options: all NEWSLETTER category templates (display: template name + language badge)
• Locale toggle (DE/EN) now also affects which templates are shown in the dropdown (filtered by locale suffix)
• “Preview” iframe uses selected template for preview render
• “Create new template” shortcut link → opens admin Email Templates tab with NEWSLETTER filter pre-applied
• Confirmation dialog for “Send Newsletter” shows selected template name: “Send newsletter using ‘[Template Name]’ to 234 subscribers?”

Key modified files:

docs/api/events.openapi.yml                                        — extend newsletter send request (FIRST)
services/event-management-service/.../service/NewsletterEmailService.java  — accept templateKey param
services/event-management-service/.../controller/NewsletterController.java — pass templateKey through
web-frontend/src/components/organizer/EventPage/EventNewsletterTab.tsx    — template selector + preview
web-frontend/src/hooks/useNewsletter/useNewsletter.ts                     — pass templateKey to API
public/locales/de/organizer.json + en/organizer.json                       — newsletter.templateSelect.* keys

Definition of Done (Story 10.14):

• Newsletter send with explicit templateKey uses that template; send without templateKey Newsletter send with explicit `templateKey` uses that template; send without `templateKey` uses default (backward compatible)
• EventNewsletterTab shows template dropdown populated from DB templates; default = `EventNewsletterTab` shows template dropdown populated from DB templates; default = `newsletter-event-{locale}`
• Preview updates immediately when different template is selected
• Confirmation dialog names the selected template
• All existing Story 10.7 tests continue to pass
• i18n: newsletter.templateSelect.* i18n: `newsletter.templateSelect.*` keys in de/en; Type-check passes

# Story 10.15: Newsletter Subscription Integrity & Language Fix

Status: ready-for-dev Prerequisite: Story 10.7 (newsletter subscriber tables + service)

User Story: As a community member, I want my newsletter subscription language preference to match the language I was browsing in when I registered, so that I receive newsletters in my preferred language — not always in German.

As an organizer, I want to confirm that all newsletter opt-in paths (public registration wizard, speaker portal registration) are wired correctly so that no subscriber is silently lost.

Background: Two gaps identified in the todo:

Gap 1 — Language hardcoding in RegistrationService: RegistrationService.createRegistration() (line 146) hardcodes "de" as the newsletter subscription language when a user opts in during registration:

newsletterSubscriberService.subscribe(request.getEmail(), request.getFirstName(), "de", "registration", username);

This should use the user’s communicationPreferences.preferredLanguage (already in the CreateRegistrationRequest DTO) or fall back to the browser Accept-Language header.

Gap 2 — Speaker portal registration: When a speaker creates their BATbern account via the self-service portal (Epic 9 / Speaker Authentication), there is no newsletter opt-in checkbox or auto-subscription. The SpeakerPortalRegistrationService (if it exists) should respect the speaker’s language preference for any newsletter subscription.

Scope:

Backend — Language Fix (RegistrationService):

• CreateRegistrationRequest already has communicationPreferences.preferredLanguage (String, nullable)
• RegistrationService.createRegistration(): replace hardcoded "de" with:
  java

  String lang = Optional.ofNullable(request.getCommunicationPreferences())
      .map(p -> p.getPreferredLanguage())
      .filter(l -> l != null && !l.isBlank())
      .orElse("de");  // fallback to German
  

• Unit test: RegistrationServiceTest — assert newsletter subscription uses preferredLanguage from request

Backend — Speaker Portal Newsletter Opt-in (if 9.x speaker auth service exists):

• If SpeakerPortalAccountService or equivalent exists in speaker-coordination-service:
  • Add newsletterOptIn: boolean field to speaker portal registration request DTO
  • On account creation: call NewsletterSubscriberService.subscribe() using speaker’s language preference if newsletterOptIn = true
  • If speaker-coordination-service cannot call newsletter service directly (cross-service boundary): emit SpeakerPortalRegisteredEvent via shared-kernel domain event; EMS consumes and subscribes
• If Epic 9 speaker auth is not yet deployed: scaffold the opt-in field in the DTO + stub the wiring; the feature becomes active when Story 9.x (Cognito account creation) is implemented

Frontend — Registration Wizard:

• RegistrationWizard.tsx Step 3 (Communication Preferences): ensure preferredLanguage field value is passed in CreateRegistrationRequest payload
• Currently the wizard likely sends the i18n language from the UI — verify and fix if not

Frontend — Speaker Portal Registration (Epic 9 alignment):

• SpeakerPortalRegistrationPage.tsx (if exists): add “Subscribe to BATbern newsletter” checkbox in account creation form, defaulting to checked

Testing — Newsletter Opt-in Integration Tests:

• NewsletterOptInIntegrationTest: POST registration with newsletterSubscribed=true + preferredLanguage=en → subscriber created with language=en
• POST registration with newsletterSubscribed=true + no language → subscriber created with language=de (fallback)
• POST registration with newsletterSubscribed=false → no subscriber created
• POST registration with newsletterSubscribed=true for already-subscribed email → idempotent (no error, subscriber unchanged)

Key modified files:

services/event-management-service/.../service/RegistrationService.java    — language from request
services/event-management-service/.../service/RegistrationServiceTest.java — new language assertions
services/speaker-coordination-service/.../ (if exists)                    — newsletter opt-in on portal registration
web-frontend/src/components/public/RegistrationWizard.tsx                  — ensure lang passed in payload

Definition of Done (Story 10.15):

• RegistrationService uses preferredLanguage `RegistrationService` uses `preferredLanguage` from request (not hardcoded "de"); unit test proves it
• Integration test: registration with preferredLanguage=fr → newsletter subscriber created with Integration test: registration with `preferredLanguage=fr` → newsletter subscriber created with `language=fr`
• Registration with newsletterSubscribed=false Registration with `newsletterSubscribed=false` → no newsletter subscriber created (negative test)
• Speaker portal newsletter opt-in wired (or scaffolded with TODO comment linked to Epic 9 story)
• No regression in existing newsletter tests (Story 10.7 suite passes)
• Type-check passes; Checkstyle passes

# Story 10.16: AI-Assisted Event Content Creation

Status: ready-for-dev Prerequisite: Story 10.2 (email template management introduces OpenAI dependency pattern)

User Story: As an organizer, I want to use AI assistance to generate a polished event description from a topic title, create a themed event image, and get a quality summary of a speaker’s abstract — so that I can produce professional event content in minutes instead of hours.

Background: The codebase has keyword-based topic classification (BatbernTopicClusterService) but no generative AI integration. The TrendingTopicsService has a comment noting “Optional — falls back gracefully when API key absent”, indicating OpenAI integration was always planned. This story introduces a controlled, optional AI layer:

• All AI calls are gated by batbern.ai.enabled: ${AI_ENABLED:false} — disabled by default; enabled in staging/prod via environment variable
• All AI calls have graceful fallbacks — if disabled or if the API call fails, the UI degrades to manual input
• OpenAI API (GPT-4o for text, DALL-E 3 for images) via the openai-java SDK

Scope:

Backend — AI Service Infrastructure:

• New dependency: com.theokanning.openai-gpt3-java:service:{version} (or com.openai:openai-java:1.x.x — latest official SDK)
• AiConfig.java: bean configuration; reads ${OPENAI_API_KEY:} and ${batbern.ai.enabled:false}; returns no-op stub when disabled
• BatbernAiService.java: central service wrapping OpenAI SDK:
  • generateEventDescription(topicTitle, topicCategory, eventNumber): String → GPT-4o prompt: “Write a 2-paragraph German event description for BATbern#{n}, a Swiss software architecture conference. Topic: {topicTitle}. Style: professional, enthusiastic, 150-200 words.”
  • generateThemeImage(topicTitle, topicCategory): String (S3 URL) → DALL-E 3 prompt: “Abstract illustration for a software architecture conference themed ‘{topicTitle}’, dark navy and blue tones, Swiss minimalist style, no text”; result uploaded to S3; returns presigned URL
  • analyzeAbstract(abstract, speakerName): AbstractAnalysisResult → GPT-4o: returns { noPromotionScore: 1-10, noPromotionFeedback: string, lessonsLearnedScore: 1-10, lessonsLearnedFeedback: string, wordCount: integer, shortenedAbstract: string|null } — scores absence-of-promotion and presence-of-lessons-learned; provides shortened German abstract when >160 words
• All methods: if (!aiEnabled) return Optional.empty() — callers handle absent result gracefully
• Results cached 1 hour by input hash via Caffeine (max 500 entries); OpenAI-side rate limits apply for burst protection
• Flyway V75: ai_generation_log table — (id, event_code, type, input_hash, generated_at, tokens_used, was_accepted) — for cost monitoring

Backend — New AI Endpoints:

# Organizer only
POST /api/v1/events/{eventCode}/ai/description
     body: { topicTitle, topicCategory }
     response: { description: string } | 503 (if AI disabled)

POST /api/v1/events/{eventCode}/ai/theme-image
     body: { topicTitle, topicCategory }
     response: { imageUrl: string, s3Key: string } | 503 (if AI disabled)

POST /api/v1/speakers/{speakerId}/ai/analyze-abstract
     body: { abstract: string, speakerName?: string }
     response: { noPromotionScore, noPromotionFeedback, lessonsLearnedScore, lessonsLearnedFeedback, wordCount, shortenedAbstract } | 503 (if AI disabled)

POST /api/v1/events/{eventCode}/ai/theme-image/apply
     body: { imageUrl: string }
     response: 200 | 404 (event not found) — persists imageUrl on event record

Frontend — AI Assist Buttons (Organizer):

Event Description (EventSettingsTab or EventOverviewTab):

• “Event Description” textarea: right-aligned “✨ Generate with AI” ghost button (only if aiEnabled=true feature flag from /api/v1/public/settings response)
• Click → loading spinner → inserts generated text into textarea (user can edit before saving)
• “Regenerate” button appears after first generation

Theme Image (EventSettingsTab):

• “Theme Image” section: “✨ Generate theme image with AI” button alongside existing file upload
• Click → “Generating image…” skeleton → generated image preview with “Use this image” / “Regenerate” / “Upload my own” choices
• “Use this image” → stores S3 key on event record via PATCH event endpoint

Abstract Analysis (QualityReviewDrawer — reached from EventSpeakersTab):

• “Analyze Abstract” button inside QualityReviewDrawer (visible to organizers only, gated on aiContentEnabled, appears only when abstract is non-empty)
• Click → inline results: two score badges (noPromotionScore, lessonsLearnedScore, each 1-10 color-coded), per-score German feedback text, optional shortened abstract accordion (when original >160 words) with copy button
• Original abstract unchanged

Frontend — AI Feature Flag:

• useFeatureFlags() hook reads from /api/v1/public/settings/presentation (or new /api/v1/public/settings/features) response
• { aiContentEnabled: boolean } — all AI UI only shown when flag is true
• Feature flag endpoint returns false when batbern.ai.enabled=false (zero frontend changes for on/off toggle)

Key new files:

services/event-management-service/src/main/resources/db/migration/V77__create_ai_generation_log.sql
services/event-management-service/.../config/AiConfig.java
services/event-management-service/.../service/BatbernAiService.java
services/event-management-service/.../service/BatbernAiServiceTest.java
services/event-management-service/.../controller/AiAssistController.java
services/event-management-service/.../controller/AiAssistControllerIntegrationTest.java
web-frontend/src/hooks/useAiAssist.ts
web-frontend/src/hooks/useFeatureFlags.ts
web-frontend/src/components/organizer/EventPage/AiAssistDrawer.tsx

Key modified files:

docs/api/events-api.openapi.yml                                         — AI assist endpoints + /apply (FIRST)
services/event-management-service/.../security/SecurityConfig.java       — permitAll for /public/settings/features
web-frontend/src/components/organizer/EventPage/EventOverviewTab.tsx     — AI description + image buttons
web-frontend/src/components/organizer/SpeakerStatus/QualityReviewDrawer.tsx — abstract analysis (design pivot: merged here)
public/locales/de/organizer.json + en/organizer.json + 8 others          — aiAssist.* keys (all 10 locales)

Definition of Done (Story 10.16): ✅ COMPLETE (2026-03-03)

• AI_ENABLED=false (default): all AI endpoints return 503; AI buttons hidden from UI (gated on useFeatureFlags().aiContentEnabled `AI_ENABLED=false` (default): all AI endpoints return 503; AI buttons hidden from UI (gated on `useFeatureFlags().aiContentEnabled`); all existing tests pass unchanged
• AI_ENABLED=true + valid OPENAI_API_KEY: description generation returns German text within 10s; image generation returns S3 URL; /apply `AI_ENABLED=true` + valid `OPENAI_API_KEY`: description generation returns German text within 10s; image generation returns S3 URL; `/apply` persists image URL on event
• Graceful degradation: if OpenAI API returns error → UI shows "KI-Generierung fehlgeschlagen, bitte manuell eingeben" toast
• ai_generation_log `ai_generation_log` table (V77) records each generation attempt with event_code, type, input_hash, generated_at
• Abstract analysis (in QualityReviewDrawer Abstract analysis (in `QualityReviewDrawer`) shows noPromotion + lessonsLearned scores with German feedback; optional shortened abstract
• TDD: BatbernAiServiceTest (6 unit tests); AiAssistControllerIntegrationTest TDD: `BatbernAiServiceTest` (6 unit tests); `AiAssistControllerIntegrationTest` (9 integration tests, including /apply)
• OpenAPI spec updated first (ADR-006): all 5 AI endpoints documented including /apply
• i18n: aiAssist.* i18n: `aiAssist.*` keys in all 10 locales; Type-check ✅; Checkstyle ✅

# Story 10.17: Email Reply-based Unsubscribe & Deregistration (Inbound Email Handler)

Status: ready-for-dev Prerequisite: Story 10.12 (deregistration service), Story 10.7 (newsletter unsubscribe)

User Story: As a subscriber or attendee, I want to unsubscribe from the newsletter or cancel my event registration simply by replying “UNSUBSCRIBE” or “CANCEL” to any email from BATbern, so that I can manage my preferences without clicking any links — especially useful on mobile.

Background: All outbound emails currently use noreply@batbern.ch. There is no inbound email processing. This story sets up AWS SES inbound email receiving and routes replies to the appropriate service action. The implementation uses the standard AWS pattern: SES Receiving → S3 (raw email storage) → SQS → Spring @SqsListener.

Scope:

AWS Infrastructure (CDK changes in infrastructure/):

• SES receiving rule set for replies@batbern.ch (separate from noreply@batbern.ch sending address)
• SES receipt rule: all mail to replies@batbern.ch → store to S3 bucket batbern-inbound-emails-{env} → send notification to SQS queue batbern-inbound-email-{env}
• IAM: EMS task role gains sqs:ReceiveMessage + sqs:DeleteMessage on inbound queue + s3:GetObject on inbound bucket
• CDK stack: InboundEmailStack (new) in infrastructure/lib/

Backend — Inbound Email Processor (event-management-service):

• New dependency: io.awspring.cloud:spring-cloud-aws-starter-sqs:{version} (already in project for other SQS work, likely)
• InboundEmailConfig.java: SQS listener bean configuration; reads ${AWS_INBOUND_EMAIL_QUEUE_URL}
• InboundEmailListenerService.java (@SqsListener):
  1. Receive SQS message (S3 event notification → raw email S3 key)
  2. Fetch raw email from S3 via S3Client.getObject()
  3. Parse MIME message with jakarta.mail.internet.MimeMessage (Java Mail API)
  4. Extract: sender email (From: header), In-Reply-To / References headers (to match original email), and first non-quoted line of plain-text body (normalized: trim, lowercase, remove punctuation)
• InboundEmailRouter.java: routes parsed email to action handler based on body content:
  • Body contains unsubscribe / abmelden / désinscription → NewsletterSubscriberService.unsubscribeByEmail(senderEmail)
  • Body contains cancel / deregister / abmelden / absagen + event code (parsed from reply subject “Re: BATbernXX Registration Confirmation”) → DeregistrationService.cancelByEmail(senderEmail, eventCode)
  • Unrecognized → log and discard; no action
• Anti-abuse: max 10 inbound emails per sender per hour (Caffeine rate limiter)
• Reply confirmation: After successful action, send a brief confirmation email (“Your newsletter subscription has been cancelled”)
• From header: Update all outbound emails to use Reply-To: replies@batbern.ch (keeping From: noreply@batbern.ch)

Key new files:

infrastructure/lib/inbound-email-stack.ts
services/event-management-service/.../config/InboundEmailConfig.java
services/event-management-service/.../service/InboundEmailListenerService.java
services/event-management-service/.../service/InboundEmailRouter.java
services/event-management-service/.../service/InboundEmailRouterTest.java
services/event-management-service/src/main/resources/email-templates/unsubscribe-confirmation-de.html
services/event-management-service/src/main/resources/email-templates/unsubscribe-confirmation-en.html

Key modified files:

infrastructure/lib/batbern-stack.ts                                — add InboundEmailStack
shared-kernel/.../service/EmailService.java                        — add Reply-To: replies@batbern.ch header
services/event-management-service/build.gradle                     — spring-cloud-aws-starter-sqs (if not present)
services/event-management-service/.../service/NewsletterSubscriberService.java — unsubscribeByEmail() method
services/event-management-service/.../service/DeregistrationService.java       — cancelByEmail() method

Definition of Done (Story 10.17):

• CDK InboundEmailStack deploys cleanly to staging; replies@batbern.ch CDK `InboundEmailStack` deploys cleanly to staging; `replies@batbern.ch` receiving rule active
• All outbound emails include Reply-To: replies@batbern.ch All outbound emails include `Reply-To: replies@batbern.ch` header
• Replying "unsubscribe" to a newsletter email → subscriber unsubscribed; confirmation email sent
• Replying "cancel" to a registration confirmation email → registration cancelled; waitlist promotion fires (Story 10.11/10.12); confirmation email sent
• Unknown reply body → silently discarded; no error; no action
• Rate limiter: >10 emails from same sender in 1h → excess messages discarded
• TDD: InboundEmailRouterTest TDD: `InboundEmailRouterTest` with mocked S3/SQS; WireMock for SES in integration test
• Confirmation email templates seeded and editable in admin Email Templates tab
• Checkstyle passes; CDK synth passes

# Story 10.18: Event Archival Task & Notification Cleanup

Status: ready-for-dev Prerequisite: None (bug fix / data cleanup — independent)

User Story: As an organizer, I want all pending tasks and in-app notifications for an event to be automatically cleaned up when the event is archived, so that my task board and notification center are not cluttered with stale items from past events.

Background (Error from todo.md): When an event transitions to ARCHIVED state via the event state machine, currently:

• Open tasks (status != completed) remain open and appear in organizer task boards
• Any queued task reminder emails continue to fire (if the scheduler window includes past-due tasks from archived events)
• In-app notifications referencing the archived event linger in the notification center

This is a data integrity bug — the EventLifecycleService (or equivalent state machine handler) does not include a cleanup step on the ARCHIVED transition.

Scope:

Backend — Archival Cleanup:

• EventArchivalCleanupService.java — called from event state machine onEntry(ARCHIVED) or EventStateTransitionHandler:
  1. Task cancellation: EventTaskRepository.findByEventIdAndStatusNot(eventId, "completed") → bulk update all to status cancelled + set cancelledReason = "Event archived" + cancelledAt = now()
  2. Task reminder suppression: ShedLock-based scheduler already queries for non-completed tasks due tomorrow — now task status = cancelled so they are naturally excluded. Verify TaskDeadlineReminderScheduler.findTasksDueForReminder() query excludes cancelled status (add if missing)
  3. Notification dismissal: NotificationRepository.findByEventCodeAndReadFalse(eventCode) → bulk mark as read = true + dismissedAt = now(); if no notification table exists, skip this step and log a warning
  4. Registration cleanup: Waitlisted registrations (status = waitlist) for the archived event → update to cancelled, cancelledReason = "Event archived". Confirmed/registered registrations → no change (historical data preserved)
• All 4 steps in a single @Transactional method; failures in steps 2-4 are caught and logged but do not roll back step 1 (task cancellation is most important)
• Idempotent: running cleanup twice has no side effects (already-cancelled tasks are skipped)

Backend — Scheduler Safety Net:

• TaskDeadlineReminderScheduler.findTasksDueForReminder() JPQL query: ensure status NOT IN ('completed', 'cancelled') (add cancelled if not already excluded)
• Unit test: scheduler does NOT send reminder for tasks belonging to ARCHIVED events

Frontend — No Changes Required:

• Task board already filters by event; once tasks are cancelled, they naturally fall into the “Cancelled” bucket (or are hidden if the task board filters by pending|in_progress only)
• Notification dismissal is backend-side; frontend already respects read=true

Key new files:

services/event-management-service/.../service/EventArchivalCleanupService.java
services/event-management-service/.../service/EventArchivalCleanupServiceTest.java

Key modified files:

services/event-management-service/.../service/EventLifecycleService.java (or EventStateTransitionHandler.java)
     — call EventArchivalCleanupService.cleanup(eventCode) on ARCHIVED transition
services/event-management-service/.../scheduler/TaskDeadlineReminderScheduler.java
     — ensure 'cancelled' excluded from reminder query
services/event-management-service/.../repository/EventTaskRepository.java
     — bulk cancel query + findByEventIdAndStatusNot
services/event-management-service/.../repository/NotificationRepository.java (if exists)
     — bulk dismiss query

Definition of Done (Story 10.18):

• TDD: EventArchivalCleanupServiceTest TDD: `EventArchivalCleanupServiceTest` written first — covers task bulk cancel, waitlist cancel, notification dismiss
• Archiving an event with 5 open tasks → all 5 tasks transition to cancelled Archiving an event with 5 open tasks → all 5 tasks transition to `cancelled` within the same transaction
• Task reminder scheduler does not send emails for tasks with status=cancelled or belonging to ARCHIVED Task reminder scheduler does not send emails for tasks with `status=cancelled` or belonging to `ARCHIVED` events
• Waitlisted registrations cancelled on archival; confirmed registrations preserved (historical)
• Cleanup is idempotent — running twice produces same result with no errors
• Integration test: archive event → verify DB state (task statuses, notification read flags)
• Checkstyle passes; no TypeScript changes needed

# Story 10.19: Remove Organizer Email from Public Presenter & About Pages

Status: ready-for-dev Prerequisite: None (pure UI cleanup — independent)

User Story: As an organizer, I want our personal email addresses removed from the public-facing About page and the moderator presentation page, so that we don’t expose team members’ private contact details to every event attendee.

Background: The OrganizerDisplay.tsx component (used on /about) renders a clickable mailto: link for every organizer whose email field is populated. The same presenter view (/present/:eventCode) displays organizer bios. The general contact email info@berner-architekten-treffen.ch already exists in the About page Contact section, making individual emails redundant.

Scope:

Frontend — OrganizerDisplay.tsx:

• Remove the {organizer.email && (<a href={mailto:…}>)} block (lines 69–76)
• The organizer portrait, name, title, and bio remain unchanged
• No backend change needed — the email field still exists in the DB/API for organizer-internal use (e.g., task notifications); it simply must not be rendered on public pages

Frontend — PresentationPage.tsx (if email is rendered):

• Audit PresentationPage.tsx and all child components (e.g., speaker bio sections, organizer credit slides) for any email renders
• Remove any public-facing mailto: or email text renders found; retain email in organizer-only internal views

Frontend — About i18n:

• If any t('contact.email') or similar keys were used solely to label the email display, remove those uses (keys themselves may remain for Contact section)
• No new i18n keys needed

Key modified files:

web-frontend/src/components/public/About/OrganizerDisplay.tsx   — remove email block
web-frontend/src/pages/PresentationPage.tsx                     — remove any email renders (if present)

Definition of Done (Story 10.19):

• /about `/about` page renders all organizer cards without any email address or mailto link
• /present/:eventCode `/present/:eventCode` renders with no organizer or speaker email addresses visible
• The Contact section on /about still shows info@berner-architekten-treffen.ch The Contact section on `/about` still shows `info@berner-architekten-treffen.ch` (unchanged)
• Organizer email field remains in DB and API (no schema change); only the UI render is removed
• Type-check passes; lint passes; no test changes needed for this pure UI removal

# Story 10.20: Legacy BAT Format Data Export & Import (Admin Tool)

Status: ready-for-dev Prerequisite: Story 10.1 (Admin page must exist to add new tab)

User Story: As an organizer, I want to export all BATbern data (events, sessions, speakers, companies, attendees, portraits, logos, and presentations) in the legacy BAT JSON format, and to import data in that same format, so that we can migrate data between system versions and maintain interoperability with the old BATspa platform.

Background: The legacy BATspa application uses a proprietary JSON export format for events, sessions, speakers, bios, companies, and attendees. Binary assets (speaker portraits, company logos, presentation files) are stored in S3. This story adds a new “Export / Import” tab (Tab 5) to the existing /organizer/admin Administration page that allows full data snapshots and restores using this format.

Scope:

Backend — Export API (event-management-service):

• New endpoint: GET /api/v1/admin/export/legacy (organizer-only)
  • Collects all events with their sessions, speaker pools, registrations (attendees)
  • Collects all companies (via HTTP call to company-user-management-service)
  • Collects all users with role SPEAKER (bio, portrait S3 key, links)
  • Serializes to the legacy BAT JSON envelope: { version, exportedAt, events[], companies[], speakers[], attendees[] }
  • Returns as application/json download (Content-Disposition: attachment; filename=batbern-export-{date}.json)
• New endpoint: GET /api/v1/admin/export/assets (organizer-only)
  • Returns a JSON manifest of presigned S3 GET URLs for all portraits, logos, and presentation PDFs/files (one URL per asset, valid 1 hour) — chosen approach: presigned URL manifest (simpler, no async complexity, no Lambda needed) (IR fix 2026-03-02: resolved “async ZIP vs manifest” ambiguity in favour of manifest)
  • Assets identified via S3 keys stored on User (portrait), Company (logo), and SessionMaterials (presentation) entities
  • Response: { exportedAt, assetCount, assets: [{ type, entityId, filename, presignedUrl }] }

Backend — Import API (event-management-service):

• New endpoint: POST /api/v1/admin/import/legacy (organizer-only, multipart/form-data)
  • Accepts file (JSON in legacy BAT format)
  • Parses and validates the envelope; returns 400 with structured error list on validation failure
  • Import strategy: upsert by legacy ID / event code — existing records updated, new records inserted, nothing deleted
  • Speaker bios and company data delegated via internal service calls (company-user-management-service)
  • Attendee registrations imported as registered status (no waitlist logic during import)
  • Returns { imported: { events: N, sessions: N, speakers: N, companies: N, attendees: N }, skipped: [...], errors: [...] }
• Portrait / logo / asset import: separate POST /api/v1/admin/import/assets endpoint
  • Accepts a ZIP file; unpacks to S3 under imports/{timestamp}/ prefix
  • Links assets to entities by filename convention matching the legacy export manifest

Frontend — New Admin Tab 5 “Export / Import”:

• web-frontend/src/components/organizer/Admin/ExportImportTab.tsx
• Export section:
  • “Export All Data (JSON)” button → triggers GET /api/v1/admin/export/legacy download
  • “Export Assets (Portraits, Logos, Presentations)” button → triggers GET /api/v1/admin/export/assets (opens presigned URL or shows ZIP progress)
• Import section:
  • JSON import: file picker (.json) + “Import” button → POST /api/v1/admin/import/legacy → shows result summary table (imported counts + skipped/error list)
  • Asset import: file picker (.zip) + “Import Assets” button → POST /api/v1/admin/import/assets
  • Confirmation dialog before import: “This will upsert data. Existing records will be updated. This cannot be undone automatically.”
• Tab added to EventManagementAdminPage.tsx as Tab 5 (index 5)

Key new files:

services/event-management-service/.../controller/AdminExportImportController.java
services/event-management-service/.../service/LegacyExportService.java
services/event-management-service/.../service/LegacyImportService.java
services/event-management-service/.../dto/LegacyExportEnvelope.java
services/event-management-service/.../dto/LegacyImportResult.java
web-frontend/src/components/organizer/Admin/ExportImportTab.tsx

Key modified files:

docs/api/events-api.openapi.yml                         — export/import endpoints (FIRST)
web-frontend/src/pages/organizer/EventManagementAdminPage.tsx — add Tab 5
public/locales/de/common.json + en/common.json          — admin.exportImport.* keys

Definition of Done (Story 10.20):

• GET /api/v1/admin/export/legacy `GET /api/v1/admin/export/legacy` returns valid legacy JSON for a seeded dataset; organizer-only (403 for others)
• POST /api/v1/admin/import/legacy `POST /api/v1/admin/import/legacy` upserts all entity types; returns structured result; idempotent (importing same file twice has no side effects)
• Asset export endpoint returns JSON presigned URL manifest ({ exportedAt, assetCount, assets: [...] } Asset export endpoint returns JSON presigned URL manifest (`{ exportedAt, assetCount, assets: [...] }`); each URL valid 1 hour; asset import ZIP is unpacked to S3 and linked to entities
• Frontend tab shows export buttons and import file pickers; result summary renders after import
• Confirmation dialog shown before any import action
• TDD: LegacyExportServiceTest and LegacyImportServiceTest TDD: `LegacyExportServiceTest` and `LegacyImportServiceTest` with mocked repositories; integration test covers round-trip (export → import → verify DB)
• OpenAPI spec committed before implementation (ADR-006)
• i18n: admin.exportImport.* i18n: `admin.exportImport.*` keys in de/en; Type-check passes; Checkstyle passes

# Story 10.21: Event Photos Gallery

Status: ready-for-dev Prerequisite: None — EventPhotosTab is added to EventPage.tsx (organizer event detail), not to the Admin page. Independent of Story 10.1. (IR fix 2026-03-02)

User Story: As an organizer, I want to upload and manage photos from each event directly in the event detail page, so that we can preserve visual memories of our events.

As a visitor, I want to see real photos from past BATbern events on the homepage — replacing the dummy testimonials — and I want to see each archived event’s own photos when I browse the archive.

Background: The homepage TestimonialSection currently shows 20 hardcoded fake testimonials in an infinite marquee. This story replaces that row with up to 20 real event photos randomly selected from the last 5 events. Each archived event detail page also gets an image marquee showing that event’s photos. Photos are stored in S3 under events/{eventCode}/photos/{filename}.

Scope:

Backend — Event Photos API (event-management-service):

• Flyway V75: New event_photos table: id (UUID PK), event_code (VARCHAR FK → events.event_code), s3_key (TEXT NOT NULL), display_url (TEXT NOT NULL), filename (TEXT), uploaded_at (TIMESTAMPTZ), uploaded_by (VARCHAR), sort_order (INT DEFAULT 0) (V74 is already taken by V74__migrate_waitlisted_to_waitlist.sql — IR fix 2026-03-02)
• New endpoints (organizer-only for write; public for read):
  • GET /api/v1/events/{eventCode}/photos → List<EventPhotoResponse> (public)
  • POST /api/v1/events/{eventCode}/photos/upload-url → presigned S3 upload URL + photoId (organizer)
  • POST /api/v1/events/{eventCode}/photos/confirm (body: photoId) → marks upload complete, stores display_url (organizer)
  • DELETE /api/v1/events/{eventCode}/photos/{photoId} → deletes DB record + S3 object (organizer)
• New endpoint for homepage use: GET /api/v1/events/recent-photos?limit=20&lastNEvents=5 → returns up to limit photo URLs randomly sampled from the last lastNEvents events (by event date)

Frontend — Organizer Event Page: Photos Tab:

• New tab “Photos” added to EventPage.tsx tab list (after existing tabs)
• web-frontend/src/components/organizer/EventPage/EventPhotosTab.tsx:
  • Photo grid (3-4 columns, thumbnails)
  • “Upload Photo” button → triggers presigned URL flow (same pattern as logo/presentation uploads)
  • Each photo card has “Delete” icon; confirmation before delete
  • Drag-to-reorder for sort_order (optional enhancement)

Frontend — Public Homepage: Replace Dummy Testimonials:

• TestimonialSection.tsx:
  • First marquee row: replace hardcoded testimonials[] array with useRecentEventPhotos(limit=20, lastNEvents=5) hook
  • If < 3 photos available (not enough data), fall back to a subset of the current testimonial cards
  • Photo cards use <img src={photo.displayUrl} alt="BATbern event" className="...rounded-lg object-cover h-48 w-64" />
  • Remove TestimonialCard component if unused after this change (or keep for fallback)

Frontend — Archive Event Detail: Photos Marquee:

• Archive event detail page (public) gets a “Photos” section below the sessions list: InfiniteMarquee showing that event’s photos (fetched via GET /api/v1/events/{eventCode}/photos)
• Only shown if the event has ≥ 1 photo; section hidden otherwise

Key new files:

services/event-management-service/src/main/resources/db/migration/V75__create_event_photos.sql
services/event-management-service/.../domain/EventPhoto.java
services/event-management-service/.../repository/EventPhotoRepository.java
services/event-management-service/.../service/EventPhotoService.java
services/event-management-service/.../controller/EventPhotoController.java
web-frontend/src/components/organizer/EventPage/EventPhotosTab.tsx
web-frontend/src/hooks/useRecentEventPhotos.ts
web-frontend/src/hooks/useEventPhotos.ts

Key modified files:

docs/api/events-api.openapi.yml                                     — photo endpoints (FIRST)
web-frontend/src/components/organizer/EventPage/EventPage.tsx       — add Photos tab
web-frontend/src/components/public/Testimonials/TestimonialSection.tsx — replace dummy data with real photos
web-frontend/src/pages/public/ArchiveEventDetailPage.tsx (or similar) — add photos marquee section
public/locales/de/events.json + en/events.json                      — photos.* keys

Definition of Done (Story 10.21):

• V75 migration runs cleanly; event_photos V75 migration runs cleanly; `event_photos` table created
• Organizer can upload photos to an event via presigned URL flow; photos appear in photo grid
• Organizer can delete a photo; S3 object and DB record both removed
• GET /api/v1/events/recent-photos `GET /api/v1/events/recent-photos` returns up to 20 photos from last 5 events (public, no auth)
• Homepage marquee shows real event photos; graceful fallback if < 3 photos exist
• Archive event detail page shows event's own photos in marquee when photos exist; section hidden otherwise
• TDD: EventPhotoServiceTest TDD: `EventPhotoServiceTest` covers upload confirmation, delete, recent-photos query
• OpenAPI spec committed before implementation (ADR-006)
• i18n: photos.* i18n: `photos.*` keys in de/en; Type-check passes; Checkstyle passes
• ❌ Drag-to-reorder (sort_order) is explicitly NOT in scope ❌ Drag-to-reorder (`sort_order`) is explicitly **NOT in scope** for this story — defer to a follow-up

# Story 10.22: Event Teaser Images on Moderator Presentation Page

Status: ready-for-dev Prerequisite: Story 10.8a (PresentationPage must exist) Updated: 2026-03-03 — expanded from single-image to multi-image design (IR review)

User Story: As an organizer, I want to upload one or more teaser images for an event from the event detail page, so that each image appears as its own full-screen slide on the moderator presentation screen — after the topic reveal and before the agenda — giving the audience a visual mood-setter sequence.

Background: The moderator presentation page (/present/:eventCode) currently shows slides: intro → topic → agenda. This story inserts one full-screen image slide per uploaded teaser image, consecutively between the topic introduction and the first agenda slide. Images are stored in S3 and managed from the event detail Settings tab. Maximum 10 images per event.

Scope:

Backend — Teaser Images (child table):

• Flyway migration: create event_teaser_images table (id UUID PK, event_code TEXT FK → events, s3_key TEXT, image_url TEXT, display_order INTEGER, created_at TIMESTAMPTZ) (check latest migration version before coding)
• EventResponse DTO: add teaserImages: List<TeaserImageItem> (empty list if none set); TeaserImageItem { id, imageUrl, displayOrder }
• New endpoints (organizer-only, max 10 images enforced at confirm):
  • POST /api/v1/events/{eventCode}/teaser-images/upload-url → { uploadUrl, s3Key, expiresIn }; S3 key: events/{eventCode}/teaser/{uuid}.{ext}
  • POST /api/v1/events/{eventCode}/teaser-images/confirm (body: { s3Key }) → TeaserImageItem; persists new row; returns 422 if already at 10 images
  • DELETE /api/v1/events/{eventCode}/teaser-images/{imageId} → 204; deletes DB row + S3 object

Frontend — Event Settings Tab (Organizer):

• EventSettingsTab.tsx: new “Teaser Images” subsection (below Registration Capacity, above Notifications)
  • Thumbnail gallery of all uploaded images; each thumbnail has a per-image remove button
  • “+ Add Teaser Image” button → presigned URL flow → on completion, gallery refetches
  • Upload button disabled when isArchived or image count ≥ 10; limit message shown at cap
  • Inline error message on upload/remove failure; gallery state unchanged on error

Frontend — Presentation Page:

• usePresentationSections.ts: loop over event.teaserImages array; push one teaser-image section per image (unique key: teaser-image-{id}, imageUrl on section object)
• New TeaserImageSlide.tsx: full-screen <img> with object-fit: cover, no overlay, no animation
• PresentationPage.tsx SectionRenderer: case 'teaser-image' → <TeaserImageSlide imageUrl={section.imageUrl} />
• If teaserImages is empty, no slides inserted; existing behaviour preserved
• Slide navigation (ArrowRight / ArrowLeft) already handles dynamic slide counts

Key new files:

services/event-management-service/src/main/resources/db/migration/V??__create_event_teaser_images.sql
services/event-management-service/.../domain/EventTeaserImage.java
services/event-management-service/.../repository/EventTeaserImageRepository.java
services/event-management-service/.../service/EventTeaserImageService.java
services/event-management-service/.../controller/EventTeaserImageController.java
web-frontend/src/pages/presentation/slides/TeaserImageSlide.tsx

Key modified files:

docs/api/events-api.openapi.yml                                        — commit FIRST (ADR-006)
services/event-management-service/.../service/EventService.java        — populate teaserImages in toDto()
web-frontend/src/hooks/usePresentationSections.ts                      — PresentationSection.imageUrl + loop
web-frontend/src/pages/PresentationPage.tsx                            — SectionRenderer case
web-frontend/src/components/organizer/EventPage/EventSettingsTab.tsx   — gallery upload UI
web-frontend/public/locales/de/events.json + en/events.json            — teaserImage.* keys
web-frontend/src/types/generated/events-api.types.ts                   — regenerate after spec change

Definition of Done (Story 10.22):

• Migration runs cleanly; event_teaser_images Migration runs cleanly; `event_teaser_images` table created; existing events unaffected
• Organizer can upload multiple teaser images via presigned URL; thumbnail gallery shown in Settings tab
• Organizer can remove any individual teaser image by ID; DB row deleted, S3 object deleted
• Presentation page shows one full-screen slide per teaser image (in displayOrder), between topic-reveal and agenda-preview
• When teaserImages When `teaserImages` is empty, presentation page renders identically to pre-story behaviour
• Max 10 images enforced: confirm returns 422 at limit; Upload button disabled and limit message shown in UI
• Upload/remove failures show inline error; gallery state unchanged
• TDD: EventTeaserImageServiceTest TDD: `EventTeaserImageServiceTest` covers upload-URL generation, confirm, delete, limit enforcement; integration test verifies DB state
• OpenAPI spec committed before implementation (ADR-006)
• i18n: teaserImage.* i18n: `teaserImage.*` keys in de/en; Type-check passes; Checkstyle passes

# Story 10.23: Event Description Section on Public Homepage

Status: ready-for-dev Prerequisite: None (field already exists in DB and API)

User Story: As a visitor, I want to read the event description on the public homepage right below the hero section, so that I can understand what this BATbern event is about before deciding to register.

Background: The Event entity already has a description (TEXT) field stored in the DB and returned in EventResponse.description. The field is settable from the organizer’s event settings panel. However, it is currently not displayed anywhere on the public-facing pages — the homepage hero goes straight from the event title/date into the speakers section. This story surfaces the description as a distinct styled section between the hero and the speakers/content sections.

Scope:

Frontend — Public Homepage:

• In HomePage.tsx (or whichever component renders the active event public view): add an EventDescriptionSection component rendered after the HeroSection and before the speaker/agenda sections
• Only rendered when activeEvent.description is non-null and non-empty; hidden otherwise (no placeholder shown to anonymous visitors)
• Component: web-frontend/src/components/public/Event/EventDescriptionSection.tsx
  • Styled card or prose block (consistent with site dark theme)
  • Renders description as formatted paragraph text (plain text stored in DB; render with white-space: pre-wrap or convert \n to <br/>)
  • Optional section heading: t('events.description.heading') → “About This Event” / “Über diese Veranstaltung”

Frontend — Archive Event Detail Page:

• If ArchiveEventDetailPage (or equivalent) renders event details, also display description in a similar prose block (if non-empty) below the event metadata and above the sessions list
• Consistent styling with homepage section

No backend changes required — EventResponse.description already populated from the existing description column (confirmed at EventResponse.java:37).

Key new files:

web-frontend/src/components/public/Event/EventDescriptionSection.tsx

Key modified files:

web-frontend/src/pages/public/HomePage.tsx                      — render EventDescriptionSection after hero
web-frontend/src/pages/public/ArchiveEventDetailPage.tsx (or equivalent) — add description block
public/locales/de/events.json + en/events.json                  — description.heading key

Definition of Done (Story 10.23):

• Homepage shows event description below the hero section when activeEvent.description Homepage shows event description below the hero section when `activeEvent.description` is non-empty
• Section is completely absent (no empty card/space) when description is null or empty
• Description text wraps correctly on mobile and desktop
• Archive event detail page also shows description when available
• No backend changes; no DB migrations needed
• i18n: events.description.heading i18n: `events.description.heading` key in all locales (10 languages); Type-check passes; lint passes

# Story 10.24: AWS Cognito User Provisioning from User Management

Status: ready-for-dev Prerequisite: Epic 9 Story 9.1 (Cognito integration patterns established)

User Story: As an organizer, I want to create an AWS Cognito account for a BATbern user directly from the User Management list — either as part of creating a new user or for an existing user who is not yet linked to AWS — so that I can onboard people without requiring them to self-register.

Architectural Clarification — Who Actually Calls AWS:

Background: The User domain entity has a nullable cognitoUserId field (cognito_user_id column). A user can exist in the BATbern DB without a Cognito account (e.g., imported from legacy data or pre-created by an organizer). This story detects that state and allows the organizer to trigger Cognito provisioning on demand. AWS Cognito’s AdminCreateUser creates the user with a temporary password and FORCE_CHANGE_PASSWORD status; the user must set a new password on first login. If a Cognito account with the same email already exists, the API returns UsernameExistsException.

Scope:

Backend — Cognito User Provisioning (company-user-management-service):

• New service: CognitoAdminService.java
  • Wraps AdminCreateUser (using software.amazon.awssdk:cognitoidentityprovider SDK, already present for Cognito sync)
  • Call parameters: email, givenName, familyName; MessageAction = SUPPRESS (no Cognito default email — BATbern sends a custom one)
  • Adds user to the appropriate Cognito group via AdminAddUserToGroup based on their BATbern role(s)
  • Sends custom welcome email via EmailService using template user-welcome-temp-password-{de,en}.html (new classpath templates seeded by EmailTemplateSeedService)
  • Catches UsernameExistsException → propagates as structured 409; does not create duplicate
  • On success: updates users.cognito_user_id with the new Cognito sub (linking DB ↔ Cognito)
• New endpoint: POST /api/v1/users/{userId}/provision-cognito (organizer-only)
  • Works for both new-user flows and existing users without a cognitoUserId
  • Body: { language } (role inferred from DB user record)
  • Returns: { cognitoUsername, temporaryPasswordSent: true } on success
  • Returns 409 if UsernameExistsException from Cognito, or if user already has a cognitoUserId
• IAM: ECS task role for company-user-management-service must have:
  • cognito-idp:AdminCreateUser on the user pool
  • cognito-idp:AdminAddUserToGroup on the user pool
  • Both added to the existing CDK IAM inline policy for this service

Frontend — User Table: Row Action Menu (UserTable.tsx):

• Add new action "linkCognito" in the Menu (alongside existing view, editRoles, delete)
• Action is only rendered when user.cognitoUserId is null/undefined:
  tsx

  {!user.cognitoUserId && (
    <MenuItem onClick={() => handleAction('linkCognito')}>
      {t('actions.createAwsAccount')}
    </MenuItem>
  )}
  

• UserList.tsx handles the 'linkCognito' action by opening a new LinkCognitoDialog for the selected user

Frontend — Link Cognito Dialog (LinkCognitoDialog.tsx):

• Simple confirmation dialog (not the full create/edit modal):
  • Title: “Create AWS Account for {firstName} {lastName}”
  • Body: “This will create an AWS Cognito account for {email}. They will receive a welcome email with a temporary password and must reset it on first login.”
  • Language selector (dropdown: DE / EN, defaults to user’s stored language)
  • “Create Account” + “Cancel” buttons
  • On confirm: calls POST /api/v1/users/{userId}/provision-cognito
  • Success state: inline success message “AWS account created. Welcome email sent to {email}.” — dialog auto-closes after 2s
  • Error (409 UsernameExistsException): “An AWS account already exists for this email address. Use the user sync function to link it.”
  • Error (other): generic error alert within dialog

Frontend — Create/Edit User Modal: “Also Create AWS Account” toggle (UserCreateEditModal.tsx):

• In create mode only (!isEditMode): add a FormControlLabel with a Switch (or Checkbox) below the role selector:
  • Label: “Also create an AWS Cognito account (send temporary password)”
  • Default: unchecked
  • When checked: language selector appears (DE / EN)
  • On form submit with toggle enabled: first calls the existing create-user endpoint, then (on success) calls POST /api/v1/users/{newUserId}/provision-cognito automatically
  • If Cognito provisioning fails after user creation: user is still created in BATbern; a warning toast appears: “User created in BATbern but AWS account creation failed. Use the ‘Create AWS Account’ action from the user list to retry.”

Note on UserResponse DTO: The cognitoUserId field does not need to be returned in the public API response (it is an internal identifier). Instead, expose a boolean hasCognitoAccount: boolean in UserResponse / the user list endpoint so the frontend can conditionally show/hide the “Create AWS Account” action without exposing the raw Cognito sub.

Email Templates (new classpath content fragments, seeded by EmailTemplateSeedService in company-user-management-service):

services/company-user-management-service/src/main/resources/email-templates/user-welcome-temp-password-de.html
services/company-user-management-service/src/main/resources/email-templates/user-welcome-temp-password-en.html

Variables: recipientName, loginUrl, temporaryPasswordNote (text block explaining first-login reset requirement).

Key new files:

services/company-user-management-service/.../service/CognitoAdminService.java
services/company-user-management-service/.../service/CognitoAdminServiceTest.java
services/company-user-management-service/.../dto/ProvisionCognitoResponse.java
web-frontend/src/components/organizer/UserManagement/LinkCognitoDialog.tsx
services/company-user-management-service/src/main/resources/email-templates/user-welcome-temp-password-de.html
services/company-user-management-service/src/main/resources/email-templates/user-welcome-temp-password-en.html

Key modified files:

docs/api/users-api.openapi.yml
     — POST /api/v1/users/{userId}/provision-cognito endpoint + hasCognitoAccount in UserResponse (FIRST)
infrastructure/lib/company-user-management-stack.ts
     — IAM policy: AdminCreateUser + AdminAddUserToGroup on user pool ARN
services/company-user-management-service/.../controller/UserController.java
     — new provision-cognito endpoint
services/company-user-management-service/.../service/UserService.java
     — update cognitoUserId after successful provisioning
services/company-user-management-service/.../dto/UserResponse.java (or generated DTO)
     — add hasCognitoAccount boolean
services/company-user-management-service/.../service/EmailTemplateSeedService.java
     — seed welcome-temp-password templates
web-frontend/src/components/organizer/UserManagement/UserTable.tsx
     — conditional "Create AWS Account" menu item based on hasCognitoAccount
web-frontend/src/components/organizer/UserManagement/UserList.tsx
     — handle 'linkCognito' action → open LinkCognitoDialog
web-frontend/src/components/organizer/UserManagement/UserCreateEditModal.tsx
     — "Also create AWS account" toggle in create mode
web-frontend/src/types/user.types.ts
     — add hasCognitoAccount to User type
public/locales/de/userManagement.json + en/userManagement.json
     — actions.createAwsAccount, linkCognito.* keys

Definition of Done (Story 10.24):

• POST /api/v1/users/{userId}/provision-cognito creates Cognito user with FORCE_CHANGE_PASSWORD; links cognitoUserId `POST /api/v1/users/{userId}/provision-cognito` creates Cognito user with `FORCE_CHANGE_PASSWORD`; links `cognitoUserId` in DB; sends custom welcome email; organizer-only (403 for non-organizers)
• Backend uses ECS IAM task role for AdminCreateUser — organizer’s own Cognito token has no AWS IAM rights; this is confirmed in a CognitoAdminServiceTest Backend uses ECS IAM task role for `AdminCreateUser` — organizer's own Cognito token has no AWS IAM rights; this is confirmed in a `CognitoAdminServiceTest` that mocks the SDK client (not Cognito tokens)
• 409 returned if email already exists in Cognito (UsernameExistsException 409 returned if email already exists in Cognito (`UsernameExistsException`) — no duplicate created, DB unchanged
• 409 returned if user already has a cognitoUserId 409 returned if user already has a `cognitoUserId` in DB
• UserResponse includes hasCognitoAccount: boolean (does not expose raw cognitoUserId `UserResponse` includes `hasCognitoAccount: boolean` (does not expose raw `cognitoUserId`)
• User table row action menu shows “Create AWS Account” only for users with User table row action menu shows "Create AWS Account" only for users with `hasCognitoAccount = false`
• LinkCognitoDialog `LinkCognitoDialog` shows confirmation, language selector, success/error states correctly
• Create-user modal toggle “Also create AWS account” triggers provisioning after DB user is created; when Cognito provisioning fails: (a) the BATbern user record is still persisted, (b) cognitoUserId Create-user modal toggle "Also create AWS account" triggers provisioning after DB user is created; when Cognito provisioning fails: (a) the BATbern user record is still persisted, (b) `cognitoUserId` remains null, (c) a warning toast is shown "User created but AWS account creation failed — use 'Create AWS Account' from the user list to retry", (d) integration test asserts DB state and toast presence
• IAM: CDK grants AdminCreateUser + AdminAddUserToGroup IAM: CDK grants `AdminCreateUser` + `AdminAddUserToGroup` scoped to the specific user pool ARN
• Welcome email templates seeded and visible/editable in Email Templates admin tab
• TDD: CognitoAdminServiceTest covers success, UsernameExistsException TDD: `CognitoAdminServiceTest` covers success, `UsernameExistsException`, SDK error, already-linked guard
• OpenAPI spec (users-api) committed before implementation (ADR-006)
• i18n: actions.createAwsAccount, linkCognito.* i18n: `actions.createAwsAccount`, `linkCognito.*` keys in de/en userManagement namespace; Type-check passes; Checkstyle passes

# Story 10.25: Partner Meeting iCal Auto-creation & Year-End Reminders

Status: ready-for-dev Prerequisite: Story 8.3 (all prerequisites below verified ✅); Story 10.2 (DB-backed email templates with admin edit UI) Note (IR 2026-03-02): ShedLock is already configured in event-management-service (V31__Add_shedlock_table.sql + shedlock-spring:5.10.0 dependency) — no setup needed. Transitive block: Story 10.2 depends on Story 10.1; if 10.1 is delayed, 10.25 is also delayed.

Audit of Story 8.3 — What is ALREADY implemented (verified by code inspection):

What was missing in Story 8.3 and is the subject of THIS story:

Note on “I only saw a status change, no real email”: In local development, when sesClient is null (no SES configured locally), EmailService logs "Would send email with N attachment(s) to: ..." and skips the send. The status chip (inviteSentAt) is still set, making it look like only a status change happened. On staging/production with a real SES client, the email with .ics attachment is actually sent. The behavior is correct — this is the expected local fallback.

User Stories:

As an organizer, I want a partner meeting to be automatically created whenever I create a new BATbern event, so that I don’t have to set it up manually each time.

As an organizer, I want the partner meeting invite email body to be editable from the admin Email Templates section (like all other system emails), so that I can customize the content without a code deploy.

As an organizer, I want a task to be automatically created on 31 December each year reminding me to send iCal invitations to partners for the coming year’s event, so we never forget partner coordination.

Scope:

Backend — Auto-create Partner Meeting on Event Creation:

• When a new BATbern event is created (saved with status CREATED), event-management-service makes a best-effort HTTP call to partner-coordination-service to auto-create the linked partner meeting
• Use the existing EventManagementClient / inter-service HTTP client pattern (partner-coordination-service already calls event-management-service via EventManagementClientImpl; the reverse direction needs a new PartnerCoordinationClient in event-management-service, or trigger from partner-service side by listening to an event)
• Simplest pattern (recommended): EventController.createEvent() or EventService.createEvent() fires a Spring ApplicationEvent EventCreatedEvent(eventCode, eventDate). A new @EventListener in event-management-service calls PartnerCoordinationClient.createMeetingForEvent(eventCode) — a one-way best-effort HTTP call (try/catch, failure only logged, does not roll back event creation)
• Auto-created PartnerMeeting fields:
  • eventCode = new event’s code
  • meetingDate = event date (populated by partner service via its own EventManagementClient.getEventSummary())
  • startTime = 12:00 (from partner.meeting.default-start-time property, default 12:00)
  • endTime = 14:00 (from partner.meeting.default-end-time property, default 14:00)
  • location = "" (empty; organizer fills in later)
  • meetingType = SPRING (default; organizer can update)
  • agenda = null, notes = null
• inviteSentAt remains null (invite not yet sent — organizer triggers manually via existing “Send Invite” button)
• Idempotent: if a PartnerMeeting with eventCode already exists, skip creation (no duplicate)

Backend — Editable Partner Meeting Invite Email Template:

• Currently PartnerInviteEmailService.buildEmailBody() returns a hardcoded German HTML string
• Replace with DB-backed template loading (Story 10.2 pattern):
  • New classpath template files seeded by EmailTemplateSeedService in partner-coordination-service (the service that sends this email):

    services/partner-coordination-service/src/main/resources/email-templates/partner-meeting-invite-de.html
    services/partner-coordination-service/src/main/resources/email-templates/partner-meeting-invite-en.html
    

  • Template variables: {{meetingDate}}, {{meetingStartTime}}, {{meetingEndTime}}, {{location}}, {{eventTitle}}, {{organizerName}}
  • PartnerInviteEmailService.sendCalendarInvites(): replace buildEmailBody() call with emailTemplateService.loadAndRender("partner-meeting-invite", language, variables) with fallback to classpath
  • Templates appear in Admin → Email Templates tab under category PARTNER
• Language: since partner users may have different language preferences, send in DE by default (or in the user’s stored language if available from UserServiceClient)

Backend — Year-End Reminder Task (Scheduler in event-management-service):

• New YearEndReminderScheduler.java (ShedLock-protected, cron 0 0 8 31 12 * — 08:00 on 31 December):
  • Creates two organizer tasks if they don’t already exist for {nextYear}:
    1. "Send partner meeting iCal invitations for {nextYear}" — due: 31 January of next year
    2. "Create BATbern event calendar entry for {nextYear}" — due: 31 January of next year
  • Assigned to all users with ORGANIZER role (fetched via UserServiceClient or internal query)
  • eventCode = null (global tasks, not tied to a specific event)
  • Idempotent: checks for existing tasks matching title + year before inserting

Frontend — No New Components Required:

• Auto-creation is fully server-side; the existing PartnerMeetingsPage list will show the auto-created meeting
• Email template appears automatically in Email Templates admin tab (seeded by EmailTemplateSeedService)
• Year-end tasks appear in the existing task board

Key new files:

services/partner-coordination-service/src/main/resources/email-templates/partner-meeting-invite-de.html
services/partner-coordination-service/src/main/resources/email-templates/partner-meeting-invite-en.html
services/event-management-service/.../scheduler/YearEndReminderScheduler.java
services/event-management-service/.../scheduler/YearEndReminderSchedulerTest.java
services/event-management-service/.../client/PartnerCoordinationClient.java  (if HTTP trigger pattern used)

Key modified files:

services/event-management-service/.../service/EventService.java (or EventController)
     — fire EventCreatedEvent after successful event save
services/event-management-service/.../listener/PartnerMeetingAutoCreateListener.java (new)
     — @EventListener on EventCreatedEvent → call PartnerCoordinationClient
services/partner-coordination-service/.../service/PartnerInviteEmailService.java
     — replace buildEmailBody() with template load + variable substitution
services/partner-coordination-service/.../service/EmailTemplateSeedService.java (new, mirrors EMS pattern)
     — seed partner-meeting-invite-de/en on startup
services/partner-coordination-service/.../repository/PartnerMeetingRepository.java
     — add existsByEventCode() for idempotent auto-creation guard

Definition of Done (Story 10.25):

• Creating a new BATbern event automatically creates a partner meeting (correct date, 12:00–14:00 defaults, empty location)
• Auto-creation is idempotent — creating the same event twice does not produce duplicate meetings
• Auto-creation failure (partner service down) does not fail or roll back event creation; error only logged
• PartnerInviteEmailService loads invite body from DB template with classpath fallback; hardcoded buildEmailBody() `PartnerInviteEmailService` loads invite body from DB template with classpath fallback; hardcoded `buildEmailBody()` removed
• partner-meeting-invite-de/en `partner-meeting-invite-de/en` templates are seeded and appear in Admin → Email Templates under category PARTNER
• YearEndReminderScheduler fires on 31 December (verified by unit test with @SpyBean `YearEndReminderScheduler` fires on 31 December (verified by unit test with `@SpyBean` / manual trigger); creates two tasks for next year; is idempotent
• Year-end tasks have due dates of 31 January of next year and are assigned to all active organizers
• TDD: PartnerMeetingAutoCreateListenerTest (mocked client, idempotency, failure isolation); YearEndReminderSchedulerTest (task creation, dedup); PartnerInviteEmailServiceTest TDD: `PartnerMeetingAutoCreateListenerTest` (mocked client, idempotency, failure isolation); `YearEndReminderSchedulerTest` (task creation, dedup); `PartnerInviteEmailServiceTest` (template load, fallback)
• No OpenAPI changes needed (no new public endpoints)
• Checkstyle passes; Type-check passes

# Story 10.26: SES Email Forwarding & Role-Based Distribution Lists

Story file: _bmad-output/implementation-artifacts/10-26-ses-email-forwarding-distribution-lists.md Status: draft Prerequisites: Story 10.17 (InboundEmailStack, SES receipt rules)

User Story: As an organizer, I want ok@batbern.ch, info@batbern.ch, events@batbern.ch, partner@batbern.ch, support@batbern.ch, and batbern{N}@batbern.ch to automatically forward emails to the right recipients based on user roles and event registrations, so that we have zero-cost distribution lists without needing any mailbox provider.

Scope:

• Extend existing InboundEmailStack with SES receipt rules for forwarding addresses
• New Lambda forwarder (Node.js 20.x) triggered by S3 events under forwarding/ prefix
• Address resolution via existing APIs (no new service endpoints):
  • ok@batbern.ch → all ORGANIZER users (organizers only can send)
  • info@batbern.ch / events@batbern.ch → all ORGANIZER users (anyone can send)
  • partner@batbern.ch → all PARTNER users (organizers only can send)
  • support@batbern.ch → configurable contacts from Admin Settings (anyone can send)
  • batbern{N}@batbern.ch → confirmed registrants of event N (organizers only can send)
• Sender authorization: organizer-only for restricted addresses; 5-min TTL cache
• Admin Settings tab on /admin page for configuring support@ forwarding recipients
• New app_settings table (key-value) in Event Management Service
• Rate-limited sending (70ms delay, matching newsletter pattern) — 300 recipients ≈ 21s, fits 60s Lambda timeout
• Route 53 MX record for batbern.ch → SES inbound SMTP
• CloudWatch metrics (EmailsForwarded, EmailsRejected, EmailsUnresolved) + alarm

Key files (estimated):

infrastructure/lib/stacks/inbound-email-stack.ts            — extended with forwarding receipt rules + Lambda
infrastructure/lambda/email-forwarder/index.ts              — new Lambda forwarder
infrastructure/lambda/email-forwarder/package.json          — new
infrastructure/test/unit/inbound-email-stack.test.ts        — extended
services/event-management-service/.../domain/AppSetting.java                    — new entity
services/event-management-service/.../repository/AppSettingRepository.java      — new repository
services/event-management-service/.../service/AdminSettingsService.java         — new service
services/event-management-service/.../controller/AdminSettingsController.java   — new controller
services/event-management-service/.../resources/db/migration/V*.sql             — new migration
web-frontend/src/components/organizer/admin/AdminSettingsTab.tsx                — new component
web-frontend/src/services/adminSettingsService.ts                               — new service

Definition of Done (Story 10.26):

• Sending email to ok@batbern.ch Sending email to `ok@batbern.ch` from organizer → delivered to all organizers
• Sending email to info@batbern.ch or events@batbern.ch Sending email to `info@batbern.ch` or `events@batbern.ch` from anyone → delivered to all organizers
• Sending email to partner@batbern.ch Sending email to `partner@batbern.ch` from organizer → delivered to all partners
• Sending email to support@batbern.ch Sending email to `support@batbern.ch` from anyone → delivered to configured support contacts
• Sending email to batbern58@batbern.ch Sending email to `batbern58@batbern.ch` from organizer → delivered to all confirmed registrants of event 58
• Non-organizer sending to ok@ / partner@ / batbern{N}@ Non-organizer sending to `ok@` / `partner@` / `batbern{N}@` → silently rejected
• Admin Settings tab visible on /admin Admin Settings tab visible on `/admin` page; support contacts configurable and persisted
• From rewritten to {name} via BATbern <noreply@batbern.ch> From rewritten to `{name} via BATbern `; Reply-To = original sender
• CloudWatch metrics published; alarm fires on >20 rejections/hour
• MX record for batbern.ch MX record for `batbern.ch` resolves to SES inbound SMTP
• CDK unit tests + Lambda Jest tests + Admin Settings integration tests all pass
• Cost: ~$0.20/month (SES free tier + Lambda free tier)

# Story 10.29: SES Bounce Processing & Newsletter List Hygiene

Story file: _bmad-output/implementation-artifacts/10-29-ses-bounce-processing-newsletter-list-hygiene.md Status: draft Prerequisites: Story 10.7 (newsletter sending), Story 10.28 (subscriber management page)

User Story: As an organizer, I want emails that permanently bounce or generate spam complaints to be automatically suppressed from future newsletter sends, so that BATbern’s SES sender reputation stays healthy and the platform’s email delivery is not disrupted.

Context: All subscribers from the old Mailman 3 mailing list (lists.hostpoint.ch) have been imported. Many of these emails likely no longer exist — email lists degrade ~2-3%/year. AWS SES flags accounts at 5% hard bounce rate and can suspend sending at 10%. Since the SES account handles ALL platform email (registrations, partner invitations, speaker coordination), a suspension would break the entire platform.

Scope:

• SES Account-Level Suppression List — enable via AWS CLI (zero code, immediate safety net)
• CDK Infrastructure — SES Configuration Set (batbern-newsletter), SNS Topic for BOUNCE + COMPLAINT events, SQS Queue for reliable processing, event destination routing
• Database Migration (V91) — add bounce_type, bounce_count, last_bounced_at, suppressed_at to newsletter_subscribers; add bounce_type, bounced_at to newsletter_recipients
• EmailService — optional configurationSetName on SendEmailRequest, controlled by Spring property
• BounceProcessingService — new @SqsListener that processes SNS-wrapped SES bounce/complaint notifications; hard bounce → immediate suppression; soft bounce → increment count, suppress after 3; complaint → immediate suppression
• Exclude suppressed from sends — modify findByUnsubscribedAtIsNull queries to also filter suppressed_at IS NULL
• Batched canary send mode — optional maxRecipients parameter + configurable inter-page delay for safe first sends to imported lists
• Admin visibility — expose bounce status (bounceType, bounceCount, suppressedAt) in subscriber list; add ?status=suppressed filter; add unsuppress action
• Monitoring — CloudWatch alarms on SES Configuration Set metrics: bounce rate >3% warning, >5% critical; complaint rate >0.05% critical

Key files (estimated):

infrastructure/lib/stacks/ses-stack.ts                                         — SES Config Set, SNS, SQS
infrastructure/lib/stacks/monitoring-stack.ts                                  — bounce rate alarms
shared-kernel/.../service/EmailService.java                                    — configurationSetName support
services/event-management-service/.../domain/NewsletterSubscriber.java         — bounce fields
services/event-management-service/.../repository/NewsletterSubscriberRepository.java — suppress filter
services/event-management-service/.../repository/NewsletterRecipientRepository.java  — bounce update
services/event-management-service/.../service/NewsletterEmailService.java      — exclude suppressed, canary mode
services/event-management-service/.../service/BounceProcessingService.java     — NEW: SQS bounce listener
services/event-management-service/.../controller/NewsletterController.java     — expose bounce status in API
services/event-management-service/src/main/resources/db/migration/V91__*.sql   — NEW: bounce columns
web-frontend/src/components/organizer/NewsletterSubscribers/                   — suppressed badge, filter

Definition of Done (Story 10.29):

• SES Account-Level Suppression List enabled (BOUNCE + COMPLAINT)
• SES Configuration Set batbern-newsletter SES Configuration Set `batbern-newsletter` created via CDK with SNS + SQS event pipeline
• Newsletter sends use configuration set (via configurationSetName on SendEmailRequest Newsletter sends use configuration set (via `configurationSetName` on `SendEmailRequest`)
• Hard bounce → subscriber suppressed_at set, Hard bounce → subscriber `suppressed_at` set, `bounce_type = 'hard'`
• Soft bounce → bounce_count Soft bounce → `bounce_count` incremented; suppressed after 3 soft bounces
• Complaint → subscriber immediately suppressed (bounce_type = 'complaint' Complaint → subscriber immediately suppressed (`bounce_type = 'complaint'`)
• Suppressed subscribers excluded from findByUnsubscribedAtIsNull Suppressed subscribers excluded from `findByUnsubscribedAtIsNull` queries (no newsletter delivery)
• Canary send mode: maxRecipients Canary send mode: `maxRecipients` parameter limits first send; configurable inter-page delay
• Admin subscriber list shows bounce status badge, filterable by Admin subscriber list shows bounce status badge, filterable by `?status=suppressed`
• Organizer can unsuppress a subscriber via admin action
• CloudWatch alarm fires on bounce rate >5% or complaint rate >0.05%
• Integration tests: BounceProcessingService processes hard/soft/complaint notifications correctly
• CDK unit tests pass for ses-stack changes
• All existing newsletter tests still pass (no regressions)

# Story 10.30: Speaker Drawer Redesign — Tabbed Layout, Organizer Assignment, Mobile UX

Story file: _bmad-output/implementation-artifacts/10-30-speaker-drawer-redesign.md Status: ready-for-dev

User Story: As an organizer, I want the speaker detail drawer to be organized into tabs (Overview, Details, Activity) with the ability to edit the assigned organizer inline, so that I can efficiently manage speaker outreach without excessive scrolling, and the drawer works properly on mobile devices.

Scope:

Backend — PATCH endpoint (Phase 1, already committed):

• PATCH /api/v1/events/{eventCode}/speakers/pool/{speakerId} — partial update for assignedOrganizerId, notes, email
• PatchSpeakerPoolRequest DTO, SpeakerPoolService.patchEntry(), controller endpoint
• Frontend service (patchSpeakerPool), type, usePatchSpeakerPool hook (Phase 2, already committed)

Frontend — Unified Tabbed Drawer (Phase 3):

• Replace 823-line SpeakerOutreachDetailsDrawer monolith with 7 decomposed components in web-frontend/src/components/organizer/SpeakerDrawer/
• Three tabs: Overview (organizer assignment, action buttons), Details (response/decline/content info), Activity (contact history + mark-contacted form)
• Default tab selection by speaker workflow state
• Content submission and quality review rendered as in-drawer sub-views (eliminates “drawer spawns drawer” pattern)
• Responsive: 520px desktop, full-width mobile, scrollable tabs, sticky action footer

Wiring & Cleanup (Phase 4–5):

• EventSpeakersTab.tsx simplified from 3 drawers + 6 state vars to 1 drawer + 2 state vars
• Delete old SpeakerOutreachDetailsDrawer.tsx, ContentSubmissionDrawer.tsx, QualityReviewDrawer.tsx
• i18n keys for tab labels
• Preserve data-testid attributes for Playwright compatibility

Acceptance Criteria:

1. AC1: Organizer can click a speaker card and see a tabbed drawer with Overview, Details, and Activity tabs
2. AC2: Default tab matches speaker state (IDENTIFIED/CONTACTED → Activity, DECLINED/CONTENT_SUBMITTED → Details, others → Overview)
3. AC3: Organizer can edit the assigned organizer via inline autocomplete on the Overview tab, saved via PATCH endpoint
4. AC4: “Submit Content” and “Review Content” render as in-drawer sub-views with back navigation (no separate drawer)
5. AC5: Contact history and mark-contacted form are in the Activity tab with full-height scrolling (no nested scroll)
6. AC6: Drawer is fully functional on mobile (full-width, scrollable tabs, sticky action footer)
7. AC7: All existing data-testid attributes preserved for Playwright E2E tests
8. AC8: Frontend builds with zero TypeScript errors; existing tests pass

Source tree (changed/new):

web-frontend/src/components/organizer/SpeakerDrawer/           — NEW directory
  SpeakerDetailDrawer.tsx                                       — Container with tabs + sub-view state
  SpeakerDrawerHeader.tsx                                       — Header: name, company, status, close
  OverviewTabPanel.tsx                                          — Organizer field, action buttons, quick info
  DetailsTabPanel.tsx                                           — Response/decline/tentative/content sections
  ActivityTabPanel.tsx                                          — Mark-contacted form + contact history
  AssignedOrganizerField.tsx                                    — Editable organizer autocomplete + PATCH
  index.ts                                                      — Barrel export
web-frontend/src/components/organizer/EventPage/EventSpeakersTab.tsx — Simplified orchestrator
web-frontend/src/components/organizer/SpeakerOutreach/SpeakerOutreachDetailsDrawer.tsx — DELETED
web-frontend/src/components/organizer/SpeakerStatus/ContentSubmissionDrawer.tsx — DELETED
web-frontend/src/components/organizer/SpeakerStatus/QualityReviewDrawer.tsx — DELETED

Definition of Done (Story 10.30):

• Tabbed drawer renders with 3 tabs (Overview, Details, Activity)
• Default tab selection logic works per speaker workflow state
• Assigned organizer editable via autocomplete, persisted via PATCH
• Content submission and quality review render in-drawer (no second drawer)
• Contact history scrolls within Activity tab without nested scrolling
• Mobile: full-width drawer, scrollable tabs, sticky action footer
• All existing data-testid All existing `data-testid` attributes preserved
• npm run build `npm run build` passes with zero errors
• Old drawer files deleted (SpeakerOutreachDetailsDrawer, ContentSubmissionDrawer, QualityReviewDrawer)
• i18n keys added for tab labels

# Story 10.31: Bot Protection — Cloudflare Turnstile for Newsletter & Event Registration

Story file: _bmad-output/implementation-artifacts/10-31-bot-protection-turnstile.md Status: ready-for-dev Source: GH#582

User Story: As a platform operator, I want newsletter subscriptions and event registrations protected by Cloudflare Turnstile, so that bot submissions are rejected before they reach domain services without degrading UX for legitimate users.

Why Turnstile:

• Privacy-first — no tracking cookies, no cross-site data collection → no cookie consent banner needed
• GDPR / Swiss nFADP compliant out of the box
• Invisible to most users (no puzzles)
• Free tier: 1M verifications/month
• No Cloudflare CDN/DNS required

Endpoints protected:

• POST /api/v1/newsletter/subscribe (NewsletterSubscribeWidget)
• POST /api/v1/events/{eventCode}/registrations (RegistrationWizard)

Cognito signup is out of scope (AWS handles its own bot protection).

Architecture:

Gateway-centralized, endpoint-selective filter: A new TurnstileVerificationFilter in api-gateway intercepts only configured endpoint patterns. Follows the existing RateLimitingFilter pattern (@Component, @Order, jakarta.servlet.Filter). Domain service controllers are untouched.

Token transport: X-Turnstile-Token HTTP header (not request body) — avoids DTO / OpenAPI spec changes.

Fail-open: If Cloudflare siteverify is unreachable, log a warning and allow the request. Legitimate users are never blocked by a third-party outage.

Feature flag: turnstile.enabled=false by default — existing behaviour is fully preserved when disabled.

Scope:

Phase 1 — Backend Config Layer:

• TurnstileProperties (@ConfigurationProperties(prefix="turnstile")) with enabled, siteKey, secretKey, verifyUrl, protectedEndpoints
• TurnstileConfigDTO — { siteKey: String } (never expose secretKey)
• FeatureFlagsDTO.turnstile: boolean + FrontendConfigDTO.turnstile: TurnstileConfigDTO
• ConfigController conditionally includes site key and feature flag
• application.yml turnstile block with ${TURNSTILE_ENABLED:false} default

Phase 2 — Backend Verification Filter:

• TurnstileVerificationFilter: @Order(Ordered.LOWEST_PRECEDENCE - 1), runs before RateLimitingFilter
• AntPathMatcher for wildcard endpoint matching (events/*/registrations)
• Missing header → 403 turnstile_required; invalid token → 403 turnstile_failed; Cloudflare unreachable → pass (fail-open)
• Full unit test coverage (6 scenarios)

Phase 3 — Frontend Hook:

• useTurnstile hook: reads useConfig(), loads Turnstile script from CDN (no npm dependency), renders invisible widget via window.turnstile
• Exports { getToken, resetWidget, widgetRef }; when disabled getToken() returns null

Phase 4 — Frontend Form Integration:

• AppConfig extended with features.turnstile + optional turnstile.siteKey
• newsletterService.subscribe() and eventApiClient.createRegistration() accept optional turnstileToken param → passed as header
• NewsletterSubscribeWidget and public RegistrationWizard integrated with useTurnstile
• 403 error handling: show user-friendly message + resetWidget()

Phase 5 — Environment Activation:

New files (7):

api-gateway/.../config/TurnstileProperties.java
api-gateway/.../config/dto/TurnstileConfigDTO.java
api-gateway/.../security/TurnstileVerificationFilter.java
api-gateway/src/test/.../security/TurnstileVerificationFilterTest.java
web-frontend/src/hooks/useTurnstile/useTurnstile.ts
web-frontend/src/hooks/useTurnstile/index.ts
web-frontend/src/hooks/useTurnstile/useTurnstile.test.ts

Modified files (12):

api-gateway/.../config/dto/FeatureFlagsDTO.java       — add boolean turnstile
api-gateway/.../config/dto/FrontendConfigDTO.java     — add TurnstileConfigDTO turnstile
api-gateway/.../config/ConfigController.java          — inject TurnstileProperties, set flags
api-gateway/src/main/resources/application.yml        — add turnstile.* block
web-frontend/src/config/runtime-config.ts             — extend AppConfig
web-frontend/src/services/newsletterService.ts        — add turnstileToken param
web-frontend/src/services/eventApiClient.ts           — add turnstileToken param
web-frontend/src/hooks/useNewsletter/useNewsletter.ts — update mutation type
web-frontend/.../NewsletterSubscribeWidget.tsx         — integrate useTurnstile
web-frontend/.../Registration/RegistrationWizard.tsx   — integrate useTurnstile
web-frontend/.../__tests__/NewsletterSubscribeWidget.test.tsx — verify header
web-frontend/.../Registration/__tests__/RegistrationWizard.test.tsx — verify header
+ CDK / ECS task definition (staging + production env vars)

Acceptance Criteria:

1. AC1: TurnstileVerificationFilter intercepts only POST /api/v1/newsletter/subscribe and POST /api/v1/events/*/registrations when enabled; all other endpoints unaffected
2. AC2: Missing X-Turnstile-Token on protected endpoints → 403 turnstile_required
3. AC3: Invalid token (Cloudflare success: false) → 403 turnstile_failed
4. AC4: Cloudflare unreachable → log warning, let request through (fail-open)
5. AC5: turnstile.enabled=false (default) → filter is a no-op; all existing behaviour preserved
6. AC6: GET /api/v1/config includes features.turnstile: boolean and optional turnstile.siteKey
7. AC7: useTurnstile hook: disabled → getToken() returns null; enabled → loads widget, returns token
8. AC8: NewsletterSubscribeWidget calls getToken() before subscribe mutation, passes header
9. AC9: RegistrationWizard calls getToken() before createRegistration(), passes header
10. AC10: 403 with turnstile_required/turnstile_failed → user-friendly error + resetWidget()
11. AC11: TurnstileVerificationFilterTest covers 6 scenarios; ./gradlew :api-gateway:test passes
12. AC12: useTurnstile.test.ts and updated component tests pass; npm run build passes
13. AC13: All existing tests pass; no regressions

Definition of Done (Story 10.31):

• TurnstileVerificationFilter `TurnstileVerificationFilter` passes all 6 unit test scenarios
• GET /api/v1/config includes features.turnstile and optional `GET /api/v1/config` includes `features.turnstile` and optional `turnstile.siteKey`
• useTurnstile `useTurnstile` hook: disabled path returns null; enabled path resolves token
• NewsletterSubscribeWidget sends X-Turnstile-Token `NewsletterSubscribeWidget` sends `X-Turnstile-Token` header when token obtained
• RegistrationWizard sends X-Turnstile-Token `RegistrationWizard` sends `X-Turnstile-Token` header when token obtained
• 403 error handling shows user-friendly message and resets widget
• turnstile.enabled=false `turnstile.enabled=false` default — local dev fully functional without any Turnstile config
• Staging configured with Cloudflare always-pass test keys
• ./gradlew :api-gateway:test `./gradlew :api-gateway:test` passes
• npm run build `npm run build` passes with zero errors
• All existing tests pass

# Story 10.32: Additional Email Addresses per User Profile

Story file: _bmad-output/implementation-artifacts/10-32-additional-user-emails.md Status: ready-for-dev Prerequisites: Story 10.26 (SES email forwarding + sender-auth Lambda) Trigger: 2026-05-20 incident — Nissim’s iPhone-Mail forward from legacy info@berner-architekten-treffen.ch to ok@batbern.ch was silently dropped because the shared mailbox is not in role_assignments for ORGANIZER.

User Story: As a logged-in user (primarily an organizer), I want to register one or more additional email addresses on my profile, so that mail forwarded or sent to me by BATbern (ok@batbern.ch fan-out, event-registration confirmations, etc.) reaches all of my addresses AND mail I send to BATbern from any of those addresses is treated as authorised — without needing my legacy/shared mailbox to be a separate BATbern user.

Scope:

• Data model: new user_additional_emails table (one row per (user, email)), unique on LOWER(email) across both user_profiles.email and user_additional_emails.email; per-user cap of 5 (configurable)
• API (CUMS): POST /users/me/additional-emails, DELETE /users/me/additional-emails/{email}; UserResponse (on GET /users/me AND GET /users) gains additionalEmails[]
• Frontend: new “Additional emails” section in UserSettingsTab.tsx → Account sub-tab (below the read-only primary email); inline add form + chip-list + delete; 13 new i18n keys in all 10 locales
• Email Forwarder Lambda (Story 10.26): sender-auth.ts getOrganizerEmails() and address-resolver.ts fetchUsersByRole() flatten primary + additional emails — closes the 2026-05-20 regression
• Registration confirmation: RegistrationEmailService.sendRegistrationConfirmation CCs additional emails when the registration belongs to a known user (anonymous registrations unchanged)
• Partner meeting calendar invites (Phase 6, added 2026-05-22): PartnerMeetingService.fetchEmailsByRole flattens primary + additional emails for both POST /partner-meetings/{id}/send-invite and the METHOD:CANCEL notice in DELETE /partner-meetings/{id}. Dedup is case-insensitive via the existing distinct() step. A null additionalEmails field on the generated client DTO is tolerated for rolling-deploy backwards-compat.
• EMS transactional senders (Phase 7, added 2026-05-22): every EMS email-sender that delivers a user-addressed transactional message now CCs the recipient’s additional emails — speaker invitations (SpeakerInvitationEmailService), speaker acceptance confirmations (SpeakerAcceptanceEmailService), speaker reminders (SpeakerReminderEmailService), quality-review revision requests (QualityReviewService.notifySpeakerOfRejection), waitlist promotion (WaitlistPromotionEmailService.sendPromotionEmail), waitlist confirmation (WaitlistPromotionEmailService.sendWaitlistConfirmationEmail). Newsletter and inbound-email confirmation replies are explicitly excluded.
• Shared-kernel EmailService plumbing (Phase 7): new sendHtmlEmail(to, cc, subject, html) async + sendHtmlEmailSync(to, cc, subject, html, configSet) overloads using SES Destination.ccAddresses. CC entries matching to case-insensitively are dropped. 3-arg sendHtmlEmail retained as a thin delegate so existing callers compile unchanged.
• PrimarySpeakerResolver.PrimarySpeakerProfile (Phase 7): 6th record field List<String> additionalEmails (compact constructor null-coerces to List.of()); backwards-compatible 5-arg secondary constructor preserves the 11 existing test fixtures.
• Audit log: ActivityHistoryEntity rows on add/remove
• Out of scope (v1): ownership verification of additional emails (column reserved); newsletter auto-routing to additional emails; Cognito primary-email change; admin-managed editing of other users’ additional emails; address-resolver.fetchEventRegistrants (event-registration distribution stays attendee-email-driven per AC15); InboundEmailConfirmationEmailService (recipients are arbitrary external senders, not registered users)

Key files (estimated):

services/company-user-management-service/.../db/migration/V16__create_user_additional_emails.sql       — NEW
services/company-user-management-service/.../domain/UserAdditionalEmail.java                            — NEW entity
services/company-user-management-service/.../repository/UserAdditionalEmailRepository.java              — NEW
services/company-user-management-service/.../domain/User.java                                           — extend with @OneToMany collection
services/company-user-management-service/.../service/UserService.java                                   — add/remove methods + audit
services/company-user-management-service/.../controller/UserController.java                             — 2 new endpoints under /me/additional-emails
docs/api/users-api.openapi.yml                                                                          — AdditionalEmail schema + 2 paths + UserResponse extension
web-frontend/src/components/user/UserSettingsTab/UserSettingsTab.tsx                                    — Account-tab section
web-frontend/src/hooks/useUserAccount/useAdditionalEmails.ts                                            — NEW hook
web-frontend/public/locales/{de,en,...,gsw-BE}/userManagement.json                                      — 13 new keys × 10 locales
infrastructure/lambda/email-forwarder/sender-auth.ts                                                    — flatten in getOrganizerEmails
infrastructure/lambda/email-forwarder/address-resolver.ts                                               — flatten in fetchUsersByRole
services/event-management-service/.../service/RegistrationEmailService.java                             — CC additional emails
bruno-tests/users/add-additional-email.bru + list + delete                                              — NEW contract tests
web-frontend/e2e/organizer/user-settings-additional-emails.spec.ts                                      — NEW Playwright spec

Definition of Done (Story 10.32):

• V16 migration applies cleanly; unique-across-primary-and-additional constraint enforced
• POST /users/me/additional-emails `POST /users/me/additional-emails` returns 201; 409 on collision (vs any primary or any additional); 422 at cap; 400 on bad format
• DELETE /users/me/additional-emails/{email} `DELETE /users/me/additional-emails/{email}` returns 204; 404 on unknown
• GET /users/me and GET /users responses include `GET /users/me` and `GET /users` responses include `additionalEmails[]`
• Organizer adds info@berner-architekten-treffen.ch → sends mail to ok@batbern.ch from that mailbox → CloudWatch shows outcome: 'forwarded', all organizers (including sender at both addresses) receive a copy. Regression test for the 2026-05-20 incident. Organizer adds `info@berner-architekten-treffen.ch` → sends mail to `ok@batbern.ch` from that mailbox → CloudWatch shows `outcome: 'forwarded'`, all organizers (including sender at both addresses) receive a copy. **Regression test for the 2026-05-20 incident.**
• User with additional emails receives event-registration confirmation at all addresses (CC); anonymous registrants unchanged
• UserSettingsTab `UserSettingsTab` Account sub-tab shows the new section; add/remove flows wired; limit alert at 5
• Bruno + Vitest + Playwright + Lambda Jest + EMS integration test suites all GREEN
• Audit-log row written on add and remove
• Backwards-compatible: Lambda continues to authorise organizers by primary email if the CUMS response is missing additionalEmails Backwards-compatible: Lambda continues to authorise organizers by primary email if the CUMS response is missing `additionalEmails` (no regression to Story 10.26 happy path)
• Phase 6 (AC23): POST /partner-meetings/{id}/send-invite returned recipientCount **Phase 6 (AC23)**: `POST /partner-meetings/{id}/send-invite` returned `recipientCount` reflects primary + additional emails across PARTNER and ORGANIZER roles; deduplicated case-insensitively
• Phase 7 (AC24): speaker invitation, speaker acceptance, speaker reminder, quality-review revision, waitlist promotion, and waitlist confirmation emails all CC the recipient’s additional emails when present (verified by verify(emailService).sendHtmlEmail(to, cc, ...) assertions in SpeakerInvitationEmailServiceTest **Phase 7 (AC24)**: speaker invitation, speaker acceptance, speaker reminder, quality-review revision, waitlist promotion, and waitlist confirmation emails all CC the recipient's additional emails when present (verified by `verify(emailService).sendHtmlEmail(to, cc, ...)` assertions in `SpeakerInvitationEmailServiceTest` + EMS sweep 1167/1167 green; shared-kernel 321/321 green; PCS 153/153 green)

Resolved Decisions (PM 2026-05-22, all 6 OQs): no ownership verification in v1 (verified_at column reserved); separate table (not JSONB / not @ElementCollection); cap = 5 (configurable); newsletter NOT auto-routed to additional emails (UI helper text explicit); additionalEmails included on every GET /users response the caller can already see; audit-log entries include the email value.

END OF EPIC 10