# Story 4.1.5b: Backend Implementation for Anonymous Event Registration

# Dependencies

Depends on: Story 4.1.5a (Registration Architecture Foundation) Blocks: Story 4.1.5 (Registration Wizard Frontend)

# Status

Not Started

# ⚡ ADR-006 Simplification

Unified user profile approach reduces implementation effort by ~50% vs dual-table (ADR-005):

• ❌ NO anonymous_* fields in Registration entity (7 fields removed)
• ❌ NO account linking logic in registrations (claimed_by, claimed_at removed)
• ✅ Simple: attendee_id always references user_profiles (anonymous users have cognito_user_id = NULL)
• ✅ Cleaner: Account linking is 3 lines of code (UPDATE user_profiles.cognito_user_id)
• ✅ Better: Company as FK to companies table (not free text)

Estimated Effort: 2-3 hours (vs 4-6 hours for ADR-005)

# Story

As a backend developer, I want to implement anonymous event registration support in the Event Management Service, so that the frontend can support both authenticated and anonymous registration flows per ADR-006 (unified user profile approach).

# Domain Context

# Primary Domain

Attendee Experience Domain (Backend support for registration)

# Involved Services

• Event Management Service (Java/Spring Boot)
• PostgreSQL (registrations table)
• API Gateway (public endpoint security configuration)

# Cross-Domain Dependencies

• Depends on: Story 4.1.5a (Migrations V9 + V11, ADR-006, OpenAPI spec)
• Integrates with: Company-User-Management Service (user_profiles for account creation and linking)
• Security Pattern: Public endpoints using confirmation code as access token
• Key ADR-006 Benefit: 85% code reduction vs dual-table (ADR-005 rejected)

# Acceptance Criteria

1. Migrations Applied: V9 (registrations) + V11 (user_profiles with nullable cognito_user_id)
2. User Profile Creation: POST /api/v1/events/{eventCode}/registrations creates user_profile with cognito_user_id = NULL for anonymous users
3. Confirmation Code Format: Generated in BAT-YYYY-NNNNNN format using PostgreSQL sequence
4. Public Retrieval: GET /api/v1/events/{eventCode}/registrations/{registrationCode} works without authentication, returns user data from user_profiles
5. Public Update: PATCH /api/v1/events/{eventCode}/registrations/{registrationCode} updates preferences without authentication
6. Public Cancellation: DELETE /api/v1/events/{eventCode}/registrations/{registrationCode} cancels registration without authentication
7. Company FK Integrity: Registration request references company_id (FK to companies table), not free text
8. Unified User Reference: registrations.attendee_id always NOT NULL (references user_profiles)
9. Security Configuration: Anonymous endpoints use permitAll(), admin endpoints remain authenticated()
10. Component Tests Pass: All registration flows tested with real PostgreSQL (Testcontainers)
11. Account Linking Works: When anonymous user creates Cognito account, user_profile.cognito_user_id updated (3 lines of code)

# Tasks / Subtasks (TDD Workflow)

# Phase 1: Database Migrations (RED Phase)

• Task 1: Apply Migrations V9 + V11 to Dev Databases **Task 1: Apply Migrations V9 + V11 to Dev Databases**
  • Event Management Service: Event Management Service: `./gradlew :services:event-management-service:flywayMigrate`
    • Verify registrations Verify `registrations` table exists (no rename - keeps existing name)
    • Verify attendee_id Verify `attendee_id` is NOT NULL (always references user_profiles)
    • Verify NO anonymous_* fields (ADR-006 unified approach)
    • Verify registration_code sequence and field created
    • Verify communication preferences fields exist
  • Company-User-Management Service: Company-User-Management Service: `./gradlew :services:company-user-management-service:flywayMigrate`
    • Verify cognito_user_id Verify `cognito_user_id` is nullable in user_profiles
    • Verify claimed_at Verify `claimed_at` field exists in user_profiles
    • Verify partial unique index on cognito_user_id (WHERE NOT NULL)
    • Verify anonymous user index (WHERE cognito_user_id IS NULL)

# Phase 2: Entity Layer Updates (GREEN Phase)

• Task 2: Update Registration Entity (Simplified - ADR-006) **Task 2: Update Registration Entity (Simplified - ADR-006)**

  • Keep @Table(name = "registrations") Keep `@Table(name = "registrations")` - NO rename needed (avoids refactoring)
  • Rename field: registrationCode → Rename field: `registrationCode` → `registrationCode`
  • Keep attendeeId as NOT NULL: @Column(nullable = false) Keep `attendeeId` as NOT NULL: `@Column(nullable = false)` (always references user_profiles)
  • Remove old fields: attendeeName, Remove old fields: `attendeeName`, `attendeeEmail`
  • NO anonymous_ fields **NO anonymous_* fields** (ADR-006: user data in user_profiles, not registrations)
  • NO account linking fields **NO account linking fields** (claimed_at is in user_profiles, not here)
  • Add preference fields:
    • newsletterSubscribed `newsletterSubscribed` (Boolean, default false)
    • eventReminders `eventReminders` (Boolean, default true)
    • specialRequests `specialRequests` (String, nullable)
    • sessionPreferences `sessionPreferences` (String[], nullable)
    • attendanceConfirmed `attendanceConfirmed` (Boolean, default false)
    • actualAttendance `actualAttendance` (Boolean, default false)
  • Add @PrePersist Add `@PrePersist` method to auto-generate confirmation code if null
  • Simplification **Simplification**: ~50% fewer fields vs ADR-005 dual-table approach

• Task 3: Update RegistrationRepository (Simplified - ADR-006) **Task 3: Update RegistrationRepository (Simplified - ADR-006)**

  • Rename method: findByEventCodeAndRegistrationCode() → Rename method: `findByEventCodeAndRegistrationCode()` → `findByEventCodeAndConfirmationCode()`
  • Add method: Add method: `findByConfirmationCode(String registrationCode)`
  • NO anonymous email methods **NO anonymous email methods** (duplicate check now by email in user_profiles, not registrations)
  • Simplification **Simplification**: Account linking happens in user_profiles (not here), so no claiming methods needed

# Phase 3: DTO Layer (GREEN Phase)

• Task 4: Create New CreateRegistrationRequest DTO **Task 4: Create New CreateRegistrationRequest DTO**

  • Match OpenAPI spec (lines 2111-2169 in events-api.openapi.yml)
  • Required fields: email, firstName, lastName, Required fields: `email`, `firstName`, `lastName`, `termsAccepted`
  • Optional fields: company, role, communicationPreferences, Optional fields: `company`, `role`, `communicationPreferences`, `specialRequests`
  • Jakarta validation annotations (@NotBlank, @Email, @Size)
  • Breaking Change: Remove attendeeUsername, attendeeName **Breaking Change**: Remove `attendeeUsername`, `attendeeName` (old pattern)

• Task 5: Create New PatchRegistrationRequest DTO **Task 5: Create New PatchRegistrationRequest DTO**

  • Match OpenAPI spec (lines 2171-2190 in events-api.openapi.yml)
  • Fields: specialRequests, Fields: `specialRequests`, `communicationPreferences`
  • Support partial updates (all fields optional)

• Task 6: Update Registration Response DTO **Task 6: Update Registration Response DTO**

  • Add registrationCode field (rename from registrationCode Add `registrationCode` field (rename from `registrationCode`)
  • Add anonymous fields (email, firstName, lastName, company, role)
  • Add preference fields (newsletterSubscribed, eventReminders, specialRequests)
  • Add account linking fields (claimedByUserId, claimedAt)
  • Conditional logic: Show anonymousEmail XOR attendeeId **Conditional logic**: Show `anonymousEmail` XOR `attendeeId` (never both)

# Phase 4: Service Layer (GREEN Phase)

• Task 7: Create RegistrationService **Task 7: Create RegistrationService**
  • Method: Method: `createAnonymousRegistration(String eventCode, CreateRegistrationRequest request)`
    • Validate event exists
    • Check for duplicate: Check for duplicate: `existsByEventCodeAndAnonymousEmail()`
    • Create Registration entity with anonymous fields
    • Generate confirmation code using sequence (handled by @PrePersist)
    • Save and return with confirmation code
  • Method: Method: `createAuthenticatedRegistration(String eventCode, UUID attendeeId, ...)`
    • Validate attendee exists (backward compatibility)
    • Create Registration entity with attendeeId
    • Generate confirmation code
    • Save and return
  • Method: Method: `getRegistrationByConfirmationCode(String eventCode, String registrationCode)`
    • Find by confirmation code
    • Return 404 if not found
    • Return DTO (hide internal UUIDs)
  • Method: Method: `updateRegistrationPreferences(String registrationCode, PatchRegistrationRequest request)`
    • Find by confirmation code
    • Update only provided fields (special requests, preferences)
    • Save and return
  • Method: Method: `cancelRegistration(String eventCode, String registrationCode)`
    • Find by confirmation code
    • Delete registration
    • Return 204 No Content

# Phase 5: Controller Layer (GREEN Phase)

• Task 8: Update RegistrationController **Task 8: Update RegistrationController**

  • BREAKING CHANGE: Rename all {registrationCode} path params → **BREAKING CHANGE**: Rename all `{registrationCode}` path params → `{registrationCode}`
  • Update POST endpoint:
    • Remove authentication requirement (will be public)
    • Use new CreateRegistrationRequest Use new `CreateRegistrationRequest` DTO
    • Call Call `RegistrationService.createAnonymousRegistration()`
    • Return 201 with confirmation code
  • Add GET endpoint: Add GET endpoint: `GET /api/v1/events/{eventCode}/registrations/{registrationCode}`
    • Public access (no authentication)
    • Call Call `RegistrationService.getRegistrationByConfirmationCode()`
    • Return 200 with registration details
    • Return 404 if not found
  • Update PATCH endpoint:
    • Change param: {registrationCode} → Change param: `{registrationCode}` → `{registrationCode}`
    • Public access (confirmation code acts as token)
    • Use new PatchRegistrationRequest Use new `PatchRegistrationRequest` DTO
    • Call Call `RegistrationService.updateRegistrationPreferences()`
    • Return 200 with updated registration
  • Update DELETE endpoint:
    • Change param: {registrationCode} → Change param: `{registrationCode}` → `{registrationCode}`
    • Public access (confirmation code acts as token)
    • Call Call `RegistrationService.cancelRegistration()`
    • Return 204 No Content

• Task 9: Add QR Code Endpoint (Story 4.1.6 dependency) **Task 9: Add QR Code Endpoint (Story 4.1.6 dependency)**

  • Add GET endpoint: Add GET endpoint: `GET /api/v1/events/{eventCode}/registrations/{registrationCode}/qr`
  • Public access (no authentication)
  • Generate QR code PNG with confirmation code + event code
  • Return image/png with proper headers
  • Support optional ?size=300 Support optional `?size=300` query parameter

# Phase 6: Security Configuration (GREEN Phase)

• Task 10: Update SecurityConfig **Task 10: Update SecurityConfig**
  • File: File: `services/event-management-service/src/main/java/ch/batbern/events/config/SecurityConfig.java`
  • Add to permitAll() Add to `permitAll()` rules:
    java

    .requestMatchers(HttpMethod.POST, "/api/v1/events/*/registrations").permitAll()  // Anonymous registration
    .requestMatchers(HttpMethod.GET, "/api/v1/events/*/registrations/*").permitAll()  // Public lookup by confirmation code
    .requestMatchers(HttpMethod.PATCH, "/api/v1/events/*/registrations/*").permitAll()  // Public update
    .requestMatchers(HttpMethod.DELETE, "/api/v1/events/*/registrations/*").permitAll()  // Public cancel
    .requestMatchers(HttpMethod.GET, "/api/v1/events/*/registrations/*/qr").permitAll()  // QR code
    

  • Keep admin endpoints authenticated: GET /api/v1/events/*/registrations Keep admin endpoints authenticated: `GET /api/v1/events/*/registrations` (list all)

# Phase 7: Component Tests (RED-GREEN-REFACTOR)

• Task 11: Write Component Tests for Anonymous Registration **Task 11: Write Component Tests for Anonymous Registration**

  • Test 11.1: Test 11.1: `should_createAnonymousRegistration_when_validDataProvided`
    • POST with email, firstName, lastName, termsAccepted
    • Verify 201 response
    • Verify confirmation code format: BAT-YYYY-NNNNNN
    • Verify anonymousEmail populated in database
    • Verify attendeeId is NULL
  • Test 11.2: Test 11.2: `should_return400_when_duplicateAnonymousEmail`
    • Create registration with email "test@example.com"
    • Try to create second registration with same email + event
    • Verify 400 Bad Request
  • Test 11.3: Test 11.3: `should_return400_when_missingRequiredFields`
    • POST without email (should fail)
    • POST without firstName (should fail)
    • POST without termsAccepted (should fail)

• Task 12: Write Component Tests for Public Retrieval **Task 12: Write Component Tests for Public Retrieval**

  • Test 12.1: Test 12.1: `should_getRegistration_when_validConfirmationCode`
    • Create anonymous registration
    • GET by confirmation code (no auth header)
    • Verify 200 response with all fields
  • Test 12.2: Test 12.2: `should_return404_when_invalidConfirmationCode`
    • GET with non-existent confirmation code
    • Verify 404 Not Found

• Task 13: Write Component Tests for Public Update **Task 13: Write Component Tests for Public Update**

  • Test 13.1: Test 13.1: `should_updatePreferences_when_validPatch`
    • Create anonymous registration
    • PATCH with new specialRequests
    • Verify 200 response
    • Verify database updated
  • Test 13.2: Test 13.2: `should_updateCommunicationPreferences_when_provided`
    • PATCH with newsletterSubscribed=true
    • Verify preference saved

• Task 14: Write Component Tests for Public Cancellation **Task 14: Write Component Tests for Public Cancellation**

  • Test 14.1: Test 14.1: `should_cancelRegistration_when_validConfirmationCode`
    • Create anonymous registration
    • DELETE by confirmation code
    • Verify 204 No Content
    • Verify deleted from database
  • Test 14.2: Test 14.2: `should_return404_when_cancellingNonExistent`
    • DELETE with invalid confirmation code
    • Verify 404 Not Found

• Task 15: Write Component Tests for Mutual Exclusivity **Task 15: Write Component Tests for Mutual Exclusivity**

  • Test 15.1: Test 15.1: `should_fail_when_bothAttendeeIdAndAnonymousEmail`
    • Try to create Registration with BOTH fields set
    • Verify database constraint violation (CHECK constraint)
  • Test 15.2: Test 15.2: `should_fail_when_neitherAttendeeIdNorAnonymousEmail`
    • Try to create Registration with NEITHER field
    • Verify database constraint violation

• Task 16: Write Component Tests for Backward Compatibility **Task 16: Write Component Tests for Backward Compatibility**

  • Test 16.1: Test 16.1: `should_createAuthenticatedRegistration_when_attendeeIdProvided`
    • Create registration with attendeeId (old pattern)
    • Verify confirmation code generated
    • Verify anonymousEmail is NULL
    • Verify attendeeId populated

# Phase 8: Integration & Documentation

• Task 17: Run All Tests **Task 17: Run All Tests**

  • Execute: Execute: `./gradlew :services:event-management-service:test`
  • Verify all 16+ new tests pass
  • Verify existing Event Management tests still pass (backward compatibility)
  • Fix any test failures

• Task 18: Update Story Documentation **Task 18: Update Story Documentation**

  • Mark all tasks complete in this story
  • Add Dev Agent Record section with implementation notes
  • Add File List section
  • Add Change Log entry
  • Update Status to "Complete"

# Dev Notes - Implementation Guide

# Confirmation Code Generation

Database Sequence (already in V9 migration):

CREATE SEQUENCE IF NOT EXISTS registration_code_seq START 1;

Entity @PrePersist Method:

@PrePersist
protected void onCreate() {
    if (this.registrationCode == null) {
        // Generate confirmation code: BAT-YYYY-NNNNNN
        int year = LocalDate.now().getYear();
        Long sequenceValue = // fetch NEXTVAL('registration_code_seq') via native query
        this.registrationCode = String.format("BAT-%d-%06d", year, sequenceValue);
    }
    this.createdAt = Instant.now();
    this.updatedAt = Instant.now();
}

Alternative (simpler): Let database DEFAULT generate confirmation code, then read it back after INSERT.

# Mutual Exclusivity Validation

Database Level (V9 migration):

ADD CONSTRAINT check_registration_type
  CHECK (
    (attendee_id IS NOT NULL AND anonymous_email IS NULL) OR
    (attendee_id IS NULL AND anonymous_email IS NOT NULL)
  );

Application Level (optional additional validation):

@PrePersist
@PreUpdate
protected void validateRegistrationType() {
    boolean hasAttendee = attendeeId != null;
    boolean hasAnonymous = anonymousEmail != null;
    if (hasAttendee && hasAnonymous) {
        throw new IllegalStateException("Registration must be EITHER authenticated OR anonymous, not both");
    }
    if (!hasAttendee && !hasAnonymous) {
        throw new IllegalStateException("Registration must have either attendeeId or anonymousEmail");
    }
}

# Security Configuration Example

SecurityConfig.java:

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        .csrf(csrf -> csrf.disable())
        .authorizeHttpRequests(auth -> auth
            // Public registration endpoints (anonymous access)
            .requestMatchers(HttpMethod.POST, "/api/v1/events/*/registrations").permitAll()
            .requestMatchers(HttpMethod.GET, "/api/v1/events/*/registrations/*").permitAll()
            .requestMatchers(HttpMethod.PATCH, "/api/v1/events/*/registrations/*").permitAll()
            .requestMatchers(HttpMethod.DELETE, "/api/v1/events/*/registrations/*").permitAll()
            .requestMatchers(HttpMethod.GET, "/api/v1/events/*/registrations/*/qr").permitAll()

            // Admin endpoints (authentication required)
            .requestMatchers(HttpMethod.GET, "/api/v1/events/*/registrations").authenticated()

            // All other requests require authentication
            .anyRequest().authenticated()
        );
    return http.build();
}

# DTO Mapping Examples

Anonymous Registration Request → Entity:

Registration registration = new Registration();
registration.setEventId(event.getId());  // Internal UUID
registration.setEventCode(eventCode);    // Public identifier
registration.setAttendeeId(null);        // Anonymous registration
registration.setAnonymousEmail(request.getEmail());
registration.setAnonymousFirstName(request.getFirstName());
registration.setAnonymousLastName(request.getLastName());
registration.setAnonymousCompany(request.getCompany());
registration.setAnonymousRole(request.getRole());
registration.setNewsletterSubscribed(request.getCommunicationPreferences().getNewsletterSubscribed());
registration.setEventReminders(request.getCommunicationPreferences().getEventReminders());
registration.setSpecialRequests(request.getSpecialRequests());
registration.setStatus("confirmed");
// registrationCode auto-generated by @PrePersist

Entity → Registration Response:

RegistrationResponse response = new RegistrationResponse();
response.setConfirmationCode(registration.getConfirmationCode());
response.setEventCode(registration.getEventCode());

// Conditional: show EITHER anonymous OR authenticated fields
if (registration.getAnonymousEmail() != null) {
    response.setAnonymousEmail(registration.getAnonymousEmail());
    response.setAnonymousFirstName(registration.getAnonymousFirstName());
    response.setAnonymousLastName(registration.getAnonymousLastName());
    response.setAnonymousCompany(registration.getAnonymousCompany());
    response.setAnonymousRole(registration.getAnonymousRole());
} else {
    response.setAttendeeId(registration.getAttendeeId());
}

response.setStatus(registration.getStatus());
response.setNewsletterSubscribed(registration.getNewsletterSubscribed());
response.setEventReminders(registration.getEventReminders());
response.setSpecialRequests(registration.getSpecialRequests());
response.setRegistrationDate(registration.getRegistrationDate());

# QR Code Generation (Story 4.1.6 dependency)

Add ZXing dependency to build.gradle:

dependencies {
    implementation 'com.google.zxing:core:3.5.1'
    implementation 'com.google.zxing:javase:3.5.1'
}

QRCodeService.java:

@Service
public class QRCodeService {
    public byte[] generateQRCode(String data, int width, int height) throws IOException {
        QRCodeWriter qrCodeWriter = new QRCodeWriter();
        BitMatrix bitMatrix = qrCodeWriter.encode(data, BarcodeFormat.QR_CODE, width, height);

        ByteArrayOutputStream pngOutputStream = new ByteArrayOutputStream();
        MatrixToImageWriter.writeToStream(bitMatrix, "PNG", pngOutputStream);
        return pngOutputStream.toByteArray();
    }
}

Controller Method:

@GetMapping("/registrations/{registrationCode}/qr")
public ResponseEntity<byte[]> getRegistrationQR(
    @PathVariable String eventCode,
    @PathVariable String registrationCode,
    @RequestParam(defaultValue = "300") int size
) throws IOException {
    Registration registration = registrationService.getRegistrationByConfirmationCode(eventCode, registrationCode);

    // Generate QR code with registration data (JSON format)
    String qrData = String.format(
        "{\"registrationCode\":\"%s\",\"eventCode\":\"%s\"}",
        registrationCode, eventCode
    );

    byte[] qrCodeImage = qrCodeService.generateQRCode(qrData, size, size);

    HttpHeaders headers = new HttpHeaders();
    headers.setContentType(MediaType.IMAGE_PNG);
    headers.setContentLength(qrCodeImage.length);

    return ResponseEntity.ok()
        .headers(headers)
        .body(qrCodeImage);
}

# Architecture Alignment

This story implements the backend portion of ADR-005 (Anonymous Event Registration):

ADR-005 Key Decisions Implemented:

• ✅ Anonymous registration without authentication (public POST endpoint)
• ✅ Confirmation code as access token (public GET/PATCH/DELETE by confirmation code)
• ✅ Email-based account linking foundation (anonymous_email field, future UserCreatedEvent handler)
• ✅ Mutually exclusive patterns (CHECK constraint enforced)
• ✅ Privacy-first design (minimal PII storage, no unnecessary authentication)

OpenAPI Spec Alignment:

• ✅ All endpoints match events-api.openapi.yml (Story 4.1.5a update)
• ✅ DTOs match schemas in lines 2111-2190
• ✅ Security patterns match security: [] annotations
• ✅ Confirmation code format matches pattern ^BAT-[0-9]{4}-[0-9]{6}$

# Breaking Changes

# 1. Table Rename

Before: @Table(name = "registrations") After: @Table(name = "registrations") Impact: All JPA queries, native SQL, and references must update

# 2. Field Rename

Before: registrationCode (String) After: registrationCode (String) Impact: All controller paths, DTOs, service methods must update

# 3. DTO Changes

Before:

CreateRegistrationRequest {
  attendeeUsername (required)
  attendeeName (required)
  attendeeEmail (required)
}

After:

CreateRegistrationRequest {
  email (required)
  firstName (required)
  lastName (required)
  company (optional)
  role (optional)
  termsAccepted (required)
}

Impact: Frontend must update API client calls

# 4. Path Parameter Changes

Before: /api/v1/events/{eventCode}/registrations/{registrationCode} After: /api/v1/events/{eventCode}/registrations/{registrationCode} Impact: Frontend routing, API client methods must update

# Testing Strategy

# Component Tests (Testcontainers)

• PostgreSQL: Use real database with V9 migration applied
• Test Data Builders: RegistrationTestDataBuilder for both patterns
• Coverage Target: >90% for new registration service methods

# Manual Testing Checklist

1. Run migration V9: ./gradlew :services:event-management-service:flywayMigrate
2. Verify table structure: \d registrations in psql
3. Test anonymous registration via curl (no auth header)
4. Test public retrieval with confirmation code
5. Test update preferences without auth
6. Test cancellation without auth
7. Test backward compatibility with authenticated registrations

# Definition of Done Checklist

# Development Complete

• All tasks completed (simplified for ADR-006)
• All 11 acceptance criteria met
• Component tests passing (>10 new tests - fewer than ADR-005 due to simplification)
• Existing Event Management tests still passing (backward compatibility)
• Migrations V9 + V11 applied successfully
• Code follows TDD practices (RED-GREEN-REFACTOR documented)
• User profile creation for anonymous users working
• Account linking (3-line UPDATE) tested

# Infrastructure Complete

• Migration V9 applied to event-management-service database
• Migration V11 applied to company-user-management-service database
• Both migrations tested with rollback scripts
• Security config updated for public endpoints
• All database constraints verified (UNIQUE, FK, partial indexes)

# Documentation Complete

• Story marked as "Complete"
• Dev Agent Record added
• File List added
• Change Log updated
• Breaking changes documented

# Review Ready

• PR created with detailed description
• Breaking changes highlighted in PR
• Migration guide included
• Component tests demonstrate all flows
• Code review completed
• QA review passed

# Change Log