# Story 4.1.5a: Architecture Consolidation for Anonymous Event Registration

# Status

In Progress

# Story

As an architect/developer, I want to consolidate and align all architecture documentation for anonymous event registration, so that stories 4.1.5 and 4.1.6 can be implemented with consistent, accurate architecture and clean normalized microservices patterns.

# Domain Context

# Primary Domain

Cross-cutting (Architecture & Documentation)

# Involved Services

• Company User Management Service (user_profiles table)
• Event Management Service (registrations table)
• API Gateway (routing and security)
• web-frontend (React 19 + TypeScript)

# Cross-Domain Dependencies

• Event Service → User Management Service (via existing UserManagementClient)
• User Management Service ← Cognito (account linking on first login)

# Requirements Context

# Related Functional Requirements

• Epic 4, Story 4.1 (Public Event Website)
• Prepares for Story 4.1.5 (Registration Wizard)
• Prepares for Story 4.1.6 (Registration Confirmation)

# Problem Statement

Current stories 4.1.5 and 4.1.6 contain architectural inconsistencies that must be resolved before implementation:

1. Wrong Endpoints: Stories reference /api/v1/registrations instead of /api/v1/events/{eventCode}/registrations
2. Wrong Registration Scope: Stories suggest session registration instead of whole-event registration
3. Data Duplication: registrations table duplicates user data (attendee_name, attendee_email) that exists in user_profiles
4. No Anonymous Support: user_profiles.cognito_id is NOT NULL, preventing anonymous registration
5. Missing ADR: No documented architecture decision for anonymous registration pattern
6. Wireframe Misalignment: Stories don’t match wireframes for registration flow

# Acceptance Criteria

1. ✅ ADR-005 created documenting anonymous registration architecture
2. ✅ Database migrations created (but not yet applied):
   • V9 Shared Kernel: Make user_profiles.cognito_id NULLABLE
   • V9 Event Management: Remove denormalized attendee fields from registrations
3. ✅ Data Architecture updated (03-data-architecture.md):
   • Fix table name: event_registrations → registrations
   • Update user_profiles schema (cognito_id NULLABLE)
   • Update registrations schema (remove attendee_name, attendee_email, attendee_id)
   • Document cross-service reference pattern
4. ✅ API Architecture updated (04-api-event-management.md):
   • Correct endpoints: /api/v1/events/{eventCode}/registrations
   • Document anonymous registration flow
   • Document UserManagementClient reuse pattern
5. ✅ OpenAPI specs updated:
   • events-api.openapi.yml: Update CreateRegistrationRequest, remove sessionIds
   • user-management-api.openapi.yml: Document user endpoints
6. ✅ Wireframes updated:
   • Add account linking CTAs and flows
   • Remove session selection references
7. ✅ Stories 4.1.5 and 4.1.6 corrected:
   • Fix endpoints
   • Remove session selection (whole-event registration only)
   • Document cross-service user creation flow
   • Reference ADR-005

# Tasks / Subtasks

# Phase 1: Create ADR-005 - Anonymous Registration Architecture

• Task 1: Create ADR-005 document **Task 1: Create ADR-005 document**
  • File: File: `docs/architecture/ADR-005-anonymous-event-registration.md`
  • Document anonymous user pattern (cognito_id=NULL)
  • Document user profile lifecycle: anonymous → authenticated
  • Document auto-linking strategy on first Cognito login (email-based matching)
  • Document cross-service communication pattern (Event Service → User Management API)
  • Document data normalization strategy (registrations store only attendee_username)
  • Document security model for anonymous registrations
  • Document account linking endpoint and flow

# Phase 2: Create Database Migrations

• Task 2: Create V9 migration for Shared Kernel (user_profiles) **Task 2: Create V9 migration for Shared Kernel (user_profiles)**

  • File: File: `shared-kernel/src/main/resources/db/migration/V9__Make_cognito_id_nullable_for_anonymous_users.sql`
  • Make cognito_user_id NULLABLE
  • Add CHECK constraint: (cognito_user_id IS NOT NULL) OR (email IS NOT NULL)
  • Add index for anonymous user lookups by email
  • Add documentation comments
  • Note **Note**: Migration created but NOT applied yet (apply during 4.1.5 implementation)

• Task 3: Create V9 migration for Event Management (registrations) **Task 3: Create V9 migration for Event Management (registrations)**

  • File: File: `services/event-management-service/src/main/resources/db/migration/V9__Remove_denormalized_attendee_data.sql`
  • DROP COLUMN attendee_name
  • DROP COLUMN attendee_email
  • DROP COLUMN attendee_id
  • Add comment: "Reference to user_profiles.username in Company User Management Service"
  • Note **Note**: Migration created but NOT applied yet (apply during 4.1.5 implementation)

# Phase 3: Update Architecture Documentation

• Task 4: Update Data Architecture (03-data-architecture.md) **Task 4: Update Data Architecture (03-data-architecture.md)**

  • Fix table name: event_registrations → registrations (Event Management Service)
  • Update user_profiles schema: cognito_user_id NULLABLE
  • Update registrations schema:
    sql

    CREATE TABLE registrations (
        id UUID PRIMARY KEY,
        event_id UUID NOT NULL REFERENCES events(id),
        registration_code VARCHAR(100) UNIQUE NOT NULL,
        attendee_username VARCHAR(100) NOT NULL,  -- Reference to user_profiles
        status VARCHAR(50) NOT NULL,
        registration_date TIMESTAMP WITH TIME ZONE,
        created_at TIMESTAMP WITH TIME ZONE,
        updated_at TIMESTAMP WITH TIME ZONE,
        UNIQUE(event_id, attendee_username)
    );
    

  • Document cross-service data access pattern (reuses existing UserManagementClient)
  • Add account linking lifecycle documentation
  • Reference ADR-005

• Task 5: Update API Architecture (04-api-event-management.md) **Task 5: Update API Architecture (04-api-event-management.md)**

  • Document correct endpoints: Document correct endpoints: `/api/v1/events/{eventCode}/registrations`
  • Document anonymous registration flow:
    1. Public user submits registration form
    2. Event Service calls User Management API to create/find user_profile (cognito_id=NULL)
    3. Event Service creates registration with attendee_username reference
  • Document cross-service communication via existing UserManagementClient
  • Document security: public POST, confirmation code access
  • Add account linking endpoint: Add account linking endpoint: `POST /api/v1/users/{username}/link-account`
  • Reference ADR-005

# Phase 4: Update OpenAPI Specifications

• Task 6: Update events-api.openapi.yml **Task 6: Update events-api.openapi.yml**

  • Update CreateRegistrationRequest Update `CreateRegistrationRequest` schema:
    • Add: firstName, lastName, company, role
    • Remove: sessionIds (whole-event registration only)
  • Update Registration Update `Registration` response model:
    • Remove: attendeeName, attendeeEmail (client must call User Management API)
    • Keep: registrationCode, attendeeUsername, eventId, status
  • Add examples for anonymous registration
  • Update endpoint documentation: Update endpoint documentation: `/api/v1/events/{eventCode}/registrations`
  • Reference ADR-005 in description

• Task 7: Create/Update user-management-api.openapi.yml **Task 7: Create/Update user-management-api.openapi.yml**

  • Create file if doesn't exist
  • Define GET /api/v1/users/{username} Define `GET /api/v1/users/{username}` - fetch user profile
  • Define GET /api/v1/users?usernames={list} Define `GET /api/v1/users?usernames={list}` - batch fetch (performance)
  • Define POST /api/v1/users/anonymous Define `POST /api/v1/users/anonymous` - create anonymous user_profile
  • Define POST /api/v1/users/{username}/link-account Define `POST /api/v1/users/{username}/link-account` - link to Cognito
  • Define UserProfile schema (with cognito_id optional)
  • Reference ADR-005

# Phase 5: Update Wireframes

• Task 8: Update story-2.4-event-registration.md wireframe **Task 8: Update story-2.4-event-registration.md wireframe**

  • Add "Create Account" CTA at bottom of registration form
  • Add note: "Registration is for the whole event, not individual sessions"
  • Clarify anonymous registration flow (no login required)
  • Update fields list: firstName, lastName, email, company, role
  • Remove any session selection references
  • Reference ADR-005

• Task 9: Update story-2.4-registration-confirmation.md wireframe **Task 9: Update story-2.4-registration-confirmation.md wireframe**

  • Add "Create Account to Manage Registrations" section with benefits:
    • View all your registrations in one place
    • Receive personalized event updates
    • Manage your profile information
  • Document account linking flow:
    1. User clicks “Create Account” button
    2. Redirected to account creation with email pre-filled
    3. On first Cognito login, auto-link to existing user_profile
  • Update endpoints to correct pattern: Update endpoints to correct pattern: `/api/v1/events/{eventCode}/registrations/{registrationCode}`
  • Reference ADR-005

# Phase 6: Correct Stories 4.1.5 and 4.1.6

• Task 10: Correct Story 4.1.5 (registration-wizard.md) **Task 10: Correct Story 4.1.5 (registration-wizard.md)**

  • Fix endpoint: POST /api/v1/registrations → Fix endpoint: ~~`POST /api/v1/registrations`~~ → `POST /api/v1/events/{eventCode}/registrations`
  • Fix endpoint: GET /api/v1/registrations/{id} → Fix endpoint: ~~`GET /api/v1/registrations/{id}`~~ → `GET /api/v1/events/{eventCode}/registrations/{registrationCode}`
  • Remove AC 3 (Step 2: Session selection)
  • Update AC: Make it 2-step wizard Update AC: Make it **2-step wizard** (Personal Info → Review & Confirm)
  • Update CreateRegistrationRequest: remove sessionIds, add firstName, lastName, company, role
  • Update SecurityConfig: .permitAll() for Update SecurityConfig: `.permitAll()` for `POST /api/v1/events/{eventCode}/registrations`
  • Document flow in Task 1:
    1. Event Service receives public registration request
    2. Event Service calls User Management API (via existing UserManagementClient)
    3. User Management creates/finds user_profile by email (cognito_id=NULL if new)
    4. Event Service creates registration with attendee_username reference
  • Remove all session selection tasks (Tasks 4, SessionSelectionStep)
  • Update component examples to reflect 2-step flow
  • Reference ADR-005
  • Note: Aligns with wireframe story-2.4-event-registration.md

• Task 11: Correct Story 4.1.6 (registration-confirmation.md) **Task 11: Correct Story 4.1.6 (registration-confirmation.md)**

  • Fix endpoints to use pattern: Fix endpoints to use pattern: `/api/v1/events/{eventCode}/registrations/{registrationCode}`
  • Add acceptance criteria: "Create Account" CTA prominently displayed
  • Add task: Implement "Create Account to Manage Registrations" section
  • Document account linking flow
  • Reference ADR-005
  • Note: Aligns with wireframe story-2.4-registration-confirmation.md

# Dev Notes - Implementation Guide

# Migration Timing

CRITICAL: The database migrations created in this story are NOT applied yet. They will be applied during the implementation of Story 4.1.5.

Reason: We want to align all documentation first, then apply schema changes together with the code implementation to maintain consistency.

# Cross-Service Architecture Pattern

This consolidation establishes a clean microservices architecture:

┌─────────────────────────────────────────────┐
│ Event Management Service                    │
│                                             │
│  registrations table:                       │
│  - id, event_id, registration_code         │
│  - attendee_username (ref to user_profiles)│
│  - status, registration_date               │
│                                             │
│  RegistrationService:                       │
│  1. Receive registration request           │
│  2. Call UserManagementClient (existing)    │
│  3. Create/find user_profile               │
│  4. Create registration with username ref   │
└─────────────────┬───────────────────────────┘
                  │ HTTP API Call
                  │ (via UserManagementClient)
                  ▼
┌─────────────────────────────────────────────┐
│ Company User Management Service             │
│                                             │
│  user_profiles table:                       │
│  - id, username, email                      │
│  - cognito_user_id (NULLABLE)              │
│  - first_name, last_name, company          │
│                                             │
│  UserService:                               │
│  - Create anonymous user (cognito_id=NULL) │
│  - Link account on first Cognito login     │
└─────────────────────────────────────────────┘

# Benefits of This Architecture

✅ Single Source of Truth: User data lives only in user_profiles ✅ No Data Duplication: registrations reference users, don’t duplicate ✅ Microservices Independence: Services communicate via APIs, not shared DB ✅ Clean Domain Boundaries: Event Service = events/registrations, User Service = users ✅ Scalable: Can cache user lookups, batch queries prevent N+1 ✅ Reuse Existing Infrastructure: Leverages existing UserManagementClient from speaker integration

# Whole-Event Registration (Not Sessions)

Decision: Registrations are for the whole event, not individual sessions.

Rationale:

• Matches wireframes (no session selection shown)
• Matches existing data model (registrations.UNIQUE(event_id, attendee_username))
• Simpler user experience
• Session preferences can be tracked separately if needed for capacity planning (future story)

# Anonymous to Authenticated Flow

Anonymous Registration (Story 4.1.5):

1. User registers without creating account
2. user_profile created with cognito_id=NULL
3. Email is unique identifier

Account Creation (Story 4.1.6+):

1. User decides to create account from confirmation page
2. Redirected to signup with email pre-filled
3. User completes Cognito registration

Auto-Linking (Post-authentication):

1. Cognito post-authentication trigger fires on first login
2. Finds user_profile by email where cognito_id IS NULL
3. Sets cognito_id on existing user_profile
4. User now has authenticated account with previous registration history

# Testing Strategy

This story is documentation-only, so testing focuses on:

1. Alignment Review: All documents reference consistent endpoints, schemas, and flows
2. ADR Completeness: ADR-005 provides clear architectural guidance
3. Migration Correctness: SQL migrations are syntactically correct (verify with --dry-run or syntax check)
4. Cross-References: All documents reference ADR-005 where appropriate
5. Wireframe Alignment: Stories match updated wireframes

No code testing required - migrations will be tested during Story 4.1.5 implementation.

# Definition of Done

• All 11 tasks completed
• 9 documentation files created/updated
• 2 database migration files created (not applied)
• Architecture review completed by team
• Stories 4.1.5 and 4.1.6 aligned with architecture
• All inconsistencies between stories, wireframes, API docs, and data model resolved
• ADR-005 approved
• Ready for Story 4.1.5 implementation

# Change Log