# Story 1.16.1: Meaningful IDs for Public-Facing URLs

# Status

Done

# Story

As a BATbern platform user (attendee, organizer, or partner), I want meaningful, human-readable URLs for events, companies, and user profiles, so that I can easily share links, remember URLs, and navigate the platform intuitively without dealing with cryptic UUIDs.

# Domain Context

# Primary Domain

Shared/Infrastructure - Cross-cutting concern affecting all bounded contexts:

• Event Management Domain (event codes for public sharing)
• Company Management Domain (company name identifiers)
• User Management Domain (username-based profiles)
• Speaker Coordination Domain (uses user identities)
• Attendee Experience Domain (content discovery via friendly URLs)

# Involved Services

• All Microservices: This is a shared-kernel infrastructure change
  • Event Management Service (event codes)
  • Company User Management Service (company names, usernames)
  • Speaker Coordination Service (uses usernames for speakers)
  • Partner Coordination Service (uses company names and usernames)
  • Attendee Experience Service (session slugs, event codes)
  • API Gateway (routing updates for friendly IDs)

# Cross-Domain Dependencies

• Shared Kernel: ID value objects (EventId, CompanyId, UserId, SessionId)
• Database Layer: All service databases need schema migrations
• API Gateway: URL routing patterns updated for friendly IDs
• Frontend: React Router and API service layer updates

# Requirements Context

# Related Functional Requirements

• FR-Infrastructure-001: Platform must support user-friendly, shareable URLs
• FR-SEO-001: Public-facing pages must have SEO-friendly URL structures
• FR-UX-001: URLs should be intuitive and memorable for end users
• FR-API-001: API endpoints must support both UUID and friendly ID lookups (transition period)

# Workflow Steps (if applicable)

Not directly tied to the 16-step event workflow, but affects:

• All Steps: Event management screens will use BATbern{number} in URLs
• Steps 2-4: Speaker coordination uses firstname.lastname identifiers
• Steps 1-16: Company references use short company names

# Acceptance Criteria Source

This is a greenfield infrastructure story. Acceptance criteria defined based on architectural requirements and user experience goals.

# Architecture Context

# Architecture Patterns

Referenced Architecture Documents:

• API Design (04-api-design.md): RESTful patterns, path parameter handling, identifier resolution
• Frontend (05-frontend-architecture.md): React Router v6 patterns, API service layer design
• Backend (06-backend-architecture.md): DDD value objects, repository patterns, service layer
• Data Models (03-data-architecture.md): Entity schemas, unique constraints, indexing strategy

Key Patterns Applied:

• Value Object Pattern: ID types encapsulate both UUID and friendly identifier
• Repository Pattern: Add findBy{FriendlyId}() methods alongside UUID lookups
• Slug Generation Pattern: German character handling, collision resolution
• Dual Identifier Strategy: UUID as primary key, friendly ID as unique alternate key

# Database Schema Reference

Architecture Schema (Source of Truth):

• Doc: docs/architecture/03-data-architecture.md
• Sections:
  • Events (Section: Event Management Service Database Schema)
  • Companies (Section: Company Management Service Database Schema)
  • Users (Section: User Management Service Database Schema)
  • Sessions (Section: Event Management Service Database Schema)

Migration Check (Dev Agent completes in Task 0):

• Existing Migrations: To be identified in Task 0
• Status: ❌ New migrations required for all entity types
• Action: Create V*__add_meaningful_ids.sql migrations for each service

Schema Changes Required:

-- Events table enhancement
ALTER TABLE events
ADD COLUMN event_code VARCHAR(20) UNIQUE NOT NULL;
CREATE UNIQUE INDEX idx_events_event_code ON events(event_code);

-- Companies table enhancement
ALTER TABLE companies
ADD COLUMN display_name VARCHAR(255) NOT NULL;
ALTER TABLE companies
ADD CONSTRAINT chk_company_name_format CHECK (name ~ '^[a-zA-Z0-9]{1,12}$');
CREATE UNIQUE INDEX idx_companies_name_lower ON companies(LOWER(name));

-- Users table enhancement
ALTER TABLE users
ADD COLUMN username VARCHAR(100) UNIQUE;
CREATE UNIQUE INDEX idx_users_username ON users(username);
ALTER TABLE users
ADD CONSTRAINT chk_username_format CHECK (username ~ '^[a-z]+\\.[a-z]+(\\.[0-9]+)?$');

-- Sessions table enhancement
ALTER TABLE sessions
ADD COLUMN slug VARCHAR(150);
CREATE UNIQUE INDEX idx_sessions_slug_event ON sessions(event_id, slug);

# Infrastructure Components

AWS Services:

• API Gateway: Route patterns updated to accept friendly IDs (/events/{eventCode} vs /events/{id})
• RDS PostgreSQL: Schema migrations, unique indexes on friendly ID columns
• ElastiCache: Cache friendly ID → UUID mappings for performance
• Lambda: No specific Lambda changes (API Gateway + ECS services)

Database Indexes (Performance Critical):

-- Events
CREATE UNIQUE INDEX idx_events_event_code ON events(event_code);

-- Companies (case-insensitive)
CREATE UNIQUE INDEX idx_companies_name_lower ON companies(LOWER(name));

-- Users
CREATE UNIQUE INDEX idx_users_username ON users(username);

-- Sessions (composite, event-scoped)
CREATE UNIQUE INDEX idx_sessions_slug_event ON sessions(event_id, slug);

# Wireframe Context

# Wireframe References

• No specific wireframes - This is backend/infrastructure focused
• Impact on existing screens:
  • Event detail URLs change from /events/{uuid} to /events/BATbern56
  • Company detail URLs change from /companies/{uuid} to /companies/GoogleZH
  • User profile URLs change from /users/{uuid} to /users/john.doe

# UI Components

New Components to Create:

1. CompanyNameField Component

   typescript

   interface CompanyNameFieldProps {
     value: string;
     onChange: (value: string) => void;
     error?: string;
     helperText?: string;
   }
   

   • Real-time validation: 12 chars max, alphanumeric only
   • Auto-sanitization: removes invalid characters
   • Material-UI TextField with InputAdornment

2. UsernameField Component

   typescript

   interface UsernameFieldProps {
     firstName: string;
     lastName: string;
     value: string;
     onChange: (value: string) => void;
     onGenerate: () => void; // Regenerate button
     error?: string;
   }
   

   • Auto-generation from first/last name
   • Collision handling UI (shows .2, .3 suffix if needed)
   • Editable with validation
   • Refresh icon button to regenerate

Modified Components:

• EventDetailScreen: Update routing, breadcrumbs to use event codes
• CompanyManagementScreen: Use company name field with validation
• UserProfileScreen: Display username prominently, allow editing

# Acceptance Criteria

# Events (AC 1-3)

1. AC1: When creating a new event, the system automatically generates an event code in format BATbern{eventNumber} where eventNumber is the sequential event number

   • Event code is unique across all events
   • Event code is stored in event_code column
   • Event code is returned in API responses as the primary identifier

2. AC2: API endpoints accept event code as path parameter

   • GET /api/v1/events/{eventCode} returns event by code (e.g., BATbern56)
   • PUT /api/v1/events/{eventCode} updates event by code
   • DELETE /api/v1/events/{eventCode} deletes event by code
   • Backend resolves event code to UUID internally

3. AC3: Frontend uses event codes in all URLs and navigation

   • Event detail page route: /events/{eventCode}
   • Session detail route: /events/{eventCode}/sessions/{sessionSlug}
   • Registration route: /events/{eventCode}/register
   • Breadcrumbs display event code (e.g., “BATbern 56”)

# Companies (AC 4-7)

4. AC4: Company name field enforces ID-compliant format in frontend

   • Maximum 12 characters
   • Alphanumeric only (a-z, A-Z, 0-9)
   • Real-time validation with clear error messages
   • Auto-sanitization removes invalid characters

5. AC5: Company entity has both name (ID) and displayName (UI label)

   • name used in URLs and as identifier (e.g., “GoogleZH”)
   • displayName shown in UI (e.g., “Google Zürich AG”)
   • Both fields required when creating company
   • Backend validates name format server-side

6. AC6: API endpoints accept company name as path parameter

   • GET /api/v1/companies/{companyName} returns company (case-insensitive)
   • PUT /api/v1/companies/{companyName} updates company
   • Company name lookup is case-insensitive (“GoogleZH” = “googlezh”)

7. AC7: Company name validation provides user-friendly feedback

   • Frontend shows character count (e.g., “8/12 characters”)
   • Error message: “Only letters and numbers allowed (no spaces)”
   • Suggestion: “Example: GoogleZH, UBS, Swisscom”

# Users (AC 8-11)

8. AC8: Username auto-generated when creating new user

   • Format: {firstname}.{lastname} (lowercase, slugified)
   • German characters converted (ä→ae, ö→oe, ü→ue)
   • Non-letter characters removed
   • Example: “Peter Müller” → “peter.mueller”

9. AC9: Username is editable in frontend during create and update

   • Username field shown with auto-generated value pre-filled
   • User can edit to custom username (must follow format)
   • Refresh button regenerates from first/last name
   • Real-time validation shows format requirements

10. AC10: Collision handling appends numeric suffix automatically

    • If “john.doe” exists, next is “john.doe.2”
    • Then “john.doe.3”, “john.doe.4”, etc.
    • Backend handles collision detection via unique constraint
    • Frontend displays collision error, offers incremented version

11. AC11: Speaker/Organizer/Partner routes use same username (role-based views)

    • /users/john.doe - Generic user profile
    • /speakers/john.doe - Speaker-specific view (same user)
    • /organizers/john.doe - Organizer-specific view (same user)
    • No separate “SpeakerId” - roles are properties on User entity

# Sessions (AC 12)

12. AC12: Session slug auto-generated from title, unique within event
    • Slugify session title (lowercase, hyphens, remove special chars)
    • Handle German characters (ä→ae, ö→oe, ü→ue, ß→ss)
    • Collision handling within event: append -2, -3, etc.
    • URL format: /events/{eventCode}/sessions/{sessionSlug}
    • Example: “Blockchain Security 101” → “blockchain-security-101”

# Test Specifications (TDD)

# Test Scenarios by Acceptance Criteria

AC1 Tests - Event Code Generation:

• should_generateEventCode_when_creatingEvent
• should_generateUniqueEventCode_when_multipleEventsCreated
• should_formatEventCodeCorrectly_when_eventNumberProvided (e.g., BATbern56)
• should_storeEventCode_when_eventPersisted

AC2 Tests - Event API Endpoints:

• should_returnEvent_when_getByEventCode
• should_return404_when_eventCodeNotFound
• should_updateEvent_when_putWithEventCode
• should_deleteEvent_when_deleteWithEventCode
• should_resolveEventCodeToUUID_when_lookupPerformed

AC3 Tests - Frontend Event Routing:

• should_navigateToEventDetail_when_eventCodeClicked
• should_displayEventCodeInBreadcrumbs_when_onEventPage
• should_loadEventData_when_routeParamIsEventCode

AC4 Tests - Company Name Validation:

• should_acceptValidCompanyName_when_alphanumericOnly
• should_rejectCompanyName_when_containsSpaces
• should_rejectCompanyName_when_containsSpecialChars
• should_rejectCompanyName_when_exceeds12Characters
• should_autoSanitize_when_invalidCharactersEntered

AC5 Tests - Company Name vs Display Name:

• should_storeNameAndDisplayName_when_companyCreated
• should_returnDisplayName_when_companyRetrieved
• should_validateNameFormat_when_serverSideValidation

AC6 Tests - Company API Endpoints:

• should_returnCompany_when_getByCompanyName
• should_returnCompany_when_getByCompanyName_caseInsensitive
• should_updateCompany_when_putWithCompanyName

AC7 Tests - Company Name UX:

• should_displayCharacterCount_when_typing
• should_showHelpText_when_fieldFocused
• should_displayErrorMessage_when_validationFails

AC8 Tests - Username Auto-Generation:

• should_generateUsername_when_userCreated
• should_convertGermanChars_when_generateUsername (ä→ae)
• should_removeNonLetters_when_generateUsername
• should_lowercaseUsername_when_generated

AC9 Tests - Username Editing:

• should_allowUsernameEdit_when_onCreate
• should_allowUsernameEdit_when_onUpdate
• should_validateFormat_when_usernameChanged
• should_regenerateUsername_when_refreshClicked

AC10 Tests - Username Collision Handling:

• should_appendSuffix_when_usernameExists
• should_incrementSuffix_when_multipleCollisions (.2, .3, .4)
• should_throwError_when_usernameNotUnique

AC11 Tests - Role-Based User Routes:

• should_loadUserProfile_when_accessViaUsersRoute
• should_loadSpeakerView_when_accessViaSpeakersRoute
• should_useSameUsername_when_differentRoleRoutes

AC12 Tests - Session Slug Generation:

• should_generateSlug_when_sessionCreated
• should_handleGermanChars_when_slugifyTitle
• should_appendSuffix_when_slugExistsInEvent
• should_allowDuplicateSlugs_when_differentEvents

# Test File Locations

Backend Tests:

Event Service Tests:
- Unit: services/event-management-service/src/test/java/ch/batbern/events/service/EventServiceTest.java
- Integration: services/event-management-service/src/test/java/ch/batbern/events/controller/EventControllerIntegrationTest.java
- Repository: services/event-management-service/src/test/java/ch/batbern/events/repository/EventRepositoryTest.java

Company Service Tests:
- Unit: services/company-user-management-service/src/test/java/ch/batbern/companyuser/service/CompanyServiceTest.java
- Integration: services/company-user-management-service/src/test/java/ch/batbern/companyuser/controller/CompanyControllerIntegrationTest.java
- Repository: services/company-user-management-service/src/test/java/ch/batbern/companyuser/repository/CompanyRepositoryTest.java

User Service Tests:
- Unit: services/company-user-management-service/src/test/java/ch/batbern/companyuser/service/UserServiceTest.java
- Integration: services/company-user-management-service/src/test/java/ch/batbern/companyuser/controller/UserControllerIntegrationTest.java

Shared Kernel Tests:
- Unit: shared-kernel/src/test/java/ch/batbern/shared/types/EventIdTest.java
- Unit: shared-kernel/src/test/java/ch/batbern/shared/types/CompanyIdTest.java
- Unit: shared-kernel/src/test/java/ch/batbern/shared/types/UserIdTest.java
- Unit: shared-kernel/src/test/java/ch/batbern/shared/service/SlugGenerationServiceTest.java

Frontend Tests:

Component Tests:
- web-frontend/src/components/Company/CompanyNameField.test.tsx
- web-frontend/src/components/User/UsernameField.test.tsx
- web-frontend/src/components/Events/EventDetailScreen.test.tsx

Service Tests:
- web-frontend/src/services/api/eventsApi.test.ts
- web-frontend/src/services/api/companiesApi.test.ts
- web-frontend/src/services/api/usersApi.test.ts

Routing Tests:
- web-frontend/src/App.test.tsx (routing scenarios)

E2E Tests:

E2E Workflows:
- bruno-tests/events-api/get-event-by-code.bru
- bruno-tests/companies-api/get-company-by-name.bru
- bruno-tests/users-api/get-user-by-username.bru

# Test Data & Mocks

Test Data Builders:

// EventTestDataBuilder
public class EventTestDataBuilder {
    private Integer eventNumber = 56;
    private String eventCode = "BATbern56";

    public EventTestDataBuilder withEventNumber(int number) {
        this.eventNumber = number;
        this.eventCode = "BATbern" + number;
        return this;
    }

    public Event build() {
        return Event.builder()
            .id(UUID.randomUUID())
            .eventNumber(eventNumber)
            .eventCode(eventCode)
            .title("Test Event " + eventNumber)
            .build();
    }
}

// UserTestDataBuilder
public class UserTestDataBuilder {
    private String firstName = "John";
    private String lastName = "Doe";
    private String username = "john.doe";

    public UserTestDataBuilder withName(String first, String last) {
        this.firstName = first;
        this.lastName = last;
        this.username = slugify(first) + "." + slugify(last);
        return this;
    }

    public User build() {
        return User.builder()
            .id(UUID.randomUUID())
            .cognitoUserId("us-east-1_test123")
            .firstName(firstName)
            .lastName(lastName)
            .username(username)
            .email(username + "@test.com")
            .build();
    }
}

Test Containers (MANDATORY):

@Testcontainers
@SpringBootTest
public abstract class AbstractIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
        .withDatabaseName("batbern_test")
        .withUsername("test")
        .withPassword("test")
        .withReuse(true);

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
        registry.add("spring.jpa.hibernate.ddl-auto", () -> "validate");
        registry.add("spring.flyway.enabled", () -> "true");
    }
}

CRITICAL: All backend integration tests MUST use PostgreSQL via Testcontainers. NO H2 or other in-memory databases.

# Tasks / Subtasks (TDD Workflow)

# Phase 1: Shared Kernel Infrastructure

• Task 1.1: Create SlugGenerationService (RED Phase) **Task 1.1: Create SlugGenerationService (RED Phase)**

  • Write failing test: Write failing test: `should_slugifyText_when_germanCharactersPresent`
  • Write failing test: Write failing test: `should_slugifyText_when_specialCharactersPresent`
  • Write failing test: Write failing test: `should_generateUsername_when_firstLastNameProvided`
  • Write failing test: Write failing test: `should_ensureUnique_when_usernameCollisionDetected`
  • Write failing test: Write failing test: `should_generateSessionSlug_when_titleProvided`
  • File: File: `shared-kernel/src/test/java/ch/batbern/shared/service/SlugGenerationServiceTest.java`

• Task 1.2: Implement SlugGenerationService (GREEN Phase) **Task 1.2: Implement SlugGenerationService (GREEN Phase)**

  • Implement slugify(String text) Implement `slugify(String text)` method with German character handling
  • Implement slugifyName(String name) Implement `slugifyName(String name)` for usernames
  • Implement generateUsername(String first, String last) Implement `generateUsername(String first, String last)` method
  • Implement ensureUniqueUsername(String baseUsername) Implement `ensureUniqueUsername(String baseUsername)` with collision handling
  • Implement generateSessionSlug(String title, UUID eventId) Implement `generateSessionSlug(String title, UUID eventId)` method
  • File: File: `shared-kernel/src/main/java/ch/batbern/shared/service/SlugGenerationService.java`
  • All tests pass (GREEN)

• Task 1.3: Update ID Value Objects (RED Phase) **Task 1.3: Update ID Value Objects (RED Phase)**

  • Write failing test: EventId.fromEventCode("BATbern56") Write failing test: `EventId.fromEventCode("BATbern56")` (AC1)
  • Write failing test: CompanyId.from("GoogleZH") Write failing test: `CompanyId.from("GoogleZH")` validates format (AC4)
  • Write failing test: UserId.fromUsername("john.doe") Write failing test: `UserId.fromUsername("john.doe")` (AC8)
  • Write failing test: SessionId.generate(title) Write failing test: `SessionId.generate(title)` creates slug
  • Files:
    • shared-kernel/src/test/java/ch/batbern/shared/types/EventIdTest.java
    • shared-kernel/src/test/java/ch/batbern/shared/types/CompanyIdTest.java
    • shared-kernel/src/test/java/ch/batbern/shared/types/UserIdTest.java
    • shared-kernel/src/test/java/ch/batbern/shared/types/SessionIdTest.java

• Task 1.4: Implement ID Value Objects (GREEN Phase) **Task 1.4: Implement ID Value Objects (GREEN Phase)**

  • Update EventId to support eventCode field and fromEventCode() Update `EventId` to support `eventCode` field and `fromEventCode()` method
  • Update CompanyId Update `CompanyId` to enforce alphanumeric 12-char validation
  • Update UserId to support username field and fromUsername() Update `UserId` to support `username` field and `fromUsername()` method
  • Create SessionId with slug Create `SessionId` with `slug` field and slug generation
  • Files:
    • shared-kernel/src/main/java/ch/batbern/shared/types/EventId.java
    • shared-kernel/src/main/java/ch/batbern/shared/types/CompanyId.java
    • shared-kernel/src/main/java/ch/batbern/shared/types/UserId.java
    • shared-kernel/src/main/java/ch/batbern/shared/types/SessionId.java (create)
  • All tests pass (GREEN)

# Phase 2: Database Migrations

• Task 2.1: Create Flyway Migrations **Task 2.1: Create Flyway Migrations**

  • Create migration: Create migration: `V20__add_event_code_column.sql`
    sql

    ALTER TABLE events ADD COLUMN event_code VARCHAR(20) UNIQUE;
    CREATE UNIQUE INDEX idx_events_event_code ON events(event_code);
    ALTER TABLE events ADD CONSTRAINT chk_event_code_format CHECK (event_code ~ '^BATbern[0-9]+$');
    

  • Create migration: Create migration: `V21__add_company_display_name.sql`
    sql

    ALTER TABLE companies ADD COLUMN display_name VARCHAR(255) NOT NULL DEFAULT 'temp';
    ALTER TABLE companies ADD CONSTRAINT chk_company_name_format CHECK (name ~ '^[a-zA-Z0-9]{1,12}$');
    CREATE UNIQUE INDEX idx_companies_name_lower ON companies(LOWER(name));
    

  • Create migration: Create migration: `V22__add_user_username.sql`
    sql

    ALTER TABLE users ADD COLUMN username VARCHAR(100) UNIQUE;
    CREATE UNIQUE INDEX idx_users_username ON users(username);
    ALTER TABLE users ADD CONSTRAINT chk_username_format CHECK (username ~ '^[a-z]+\\.[a-z]+(\\.[0-9]+)?$');
    

  • Create migration: Create migration: `V23__add_session_slug.sql`
    sql

    ALTER TABLE sessions ADD COLUMN slug VARCHAR(150);
    CREATE UNIQUE INDEX idx_sessions_slug_event ON sessions(event_id, slug);
    

  • Files:
    • services/event-management-service/src/main/resources/db/migration/V20__*.sql
    • services/company-user-management-service/src/main/resources/db/migration/V21__*.sql
    • services/company-user-management-service/src/main/resources/db/migration/V22__*.sql
    • services/event-management-service/src/main/resources/db/migration/V23__*.sql

• Task 2.2: Test Migrations with Testcontainers **Task 2.2: Test Migrations with Testcontainers**

  • Run integration tests with Flyway migrations enabled
  • Verify indexes created successfully
  • Verify constraints work as expected
  • Verify no migration conflicts

# Phase 3: Backend - Event Service

• Task 3.1: Event Repository Methods (RED Phase) **Task 3.1: Event Repository Methods (RED Phase)** (AC2)

  • Write failing test: Write failing test: `EventRepository.findByEventCode("BATbern56")`
  • Write failing test: Write failing test: `EventRepository.existsByEventCode(String code)`
  • File: File: `services/event-management-service/src/test/java/ch/batbern/events/repository/EventRepositoryTest.java`

• Task 3.2: Event Repository Implementation (GREEN Phase) **Task 3.2: Event Repository Implementation (GREEN Phase)** (AC2)

  • Add method: Add method: `Optional findByEventCode(String eventCode);`
  • Add method: Add method: `boolean existsByEventCode(String eventCode);`
  • File: File: `services/event-management-service/src/main/java/ch/batbern/events/repository/EventRepository.java`
  • Tests pass (GREEN)

• Task 3.3: Event Service Logic (RED Phase) **Task 3.3: Event Service Logic (RED Phase)** (AC1, AC2)

  • Write failing test: EventService.create() Write failing test: `EventService.create()` generates event code
  • Write failing test: EventService.findByEventCode() Write failing test: `EventService.findByEventCode()` resolves to event
  • Write failing test: event code auto-increments based on max event_number
  • File: File: `services/event-management-service/src/test/java/ch/batbern/events/service/EventServiceTest.java`

• Task 3.4: Event Service Implementation (GREEN Phase) **Task 3.4: Event Service Implementation (GREEN Phase)** (AC1, AC2)

  • Implement event code generation on create: Implement event code generation on create: `eventCode = "BATbern" + eventNumber`
  • Implement findByEventCode(String code) Implement `findByEventCode(String code)` method
  • Update entity to include eventCode Update entity to include `eventCode` field with JPA annotation
  • Files:
    • services/event-management-service/src/main/java/ch/batbern/events/service/EventService.java
    • services/event-management-service/src/main/java/ch/batbern/events/domain/Event.java
  • Tests pass (GREEN)

• Task 3.5: Event Controller Endpoints (RED Phase) **Task 3.5: Event Controller Endpoints (RED Phase)** (AC2)

  • Write failing integration test: Write failing integration test: `GET /api/v1/events/{eventCode}`
  • Write failing integration test: Write failing integration test: `PUT /api/v1/events/{eventCode}`
  • Write failing integration test: Write failing integration test: `DELETE /api/v1/events/{eventCode}`
  • File: File: `services/event-management-service/src/test/java/ch/batbern/events/controller/EventControllerIntegrationTest.java`

• Task 3.6: Event Controller Implementation (GREEN Phase) **Task 3.6: Event Controller Implementation (GREEN Phase)** (AC2)

  • Update @GetMapping("/{eventCode}") Update `@GetMapping("/{eventCode}")` to accept event code
  • Update @PutMapping("/{eventCode}") Update `@PutMapping("/{eventCode}")` to accept event code
  • Update @DeleteMapping("/{eventCode}") Update `@DeleteMapping("/{eventCode}")` to accept event code
  • Add helper method to detect UUID vs event code pattern
  • File: File: `services/event-management-service/src/main/java/ch/batbern/events/controller/EventController.java`
  • Tests pass (GREEN)

# Phase 4: Backend - Company Service

• Task 4.1: Company Repository Methods (RED Phase) **Task 4.1: Company Repository Methods (RED Phase)** (AC6)

  • Write failing test: Write failing test: `CompanyRepository.findByNameIgnoreCase(String name)`
  • Write failing test: Write failing test: `CompanyRepository.existsByNameIgnoreCase(String name)`
  • File: File: `services/company-user-management-service/src/test/java/ch/batbern/companyuser/repository/CompanyRepositoryTest.java`

• Task 4.2: Company Repository Implementation (GREEN Phase) **Task 4.2: Company Repository Implementation (GREEN Phase)** (AC6)

  • Add method: Add method: `Optional findByNameIgnoreCase(String name);`
  • Add method: Add method: `boolean existsByNameIgnoreCase(String name);`
  • File: File: `services/company-user-management-service/src/main/java/ch/batbern/companyuser/repository/CompanyRepository.java`
  • Tests pass (GREEN)

• Task 4.3: Company Service Logic (RED Phase) **Task 4.3: Company Service Logic (RED Phase)** (AC5, AC6)

  • Write failing test: create company with name + displayName
  • Write failing test: validate name format (12 char, alphanumeric)
  • Write failing test: case-insensitive lookup
  • File: File: `services/company-user-management-service/src/test/java/ch/batbern/companyuser/service/CompanyServiceTest.java`

• Task 4.4: Company Service Implementation (GREEN Phase) **Task 4.4: Company Service Implementation (GREEN Phase)** (AC5, AC6)

  • Implement create() Implement `create()` with name format validation
  • Implement findByName(String name) Implement `findByName(String name)` case-insensitive
  • Update Company entity: add displayName Update Company entity: add `displayName` field
  • Files:
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/service/CompanyService.java
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/domain/Company.java
  • Tests pass (GREEN)

• Task 4.5: Company Controller & DTOs (RED Phase) **Task 4.5: Company Controller & DTOs (RED Phase)** (AC6, AC7)

  • Write failing test: Write failing test: `GET /api/v1/companies/{companyName}`
  • Write failing test: POST /api/v1/companies Write failing test: `POST /api/v1/companies` with validation
  • Write failing test: validation error response format
  • File: File: `services/company-user-management-service/src/test/java/ch/batbern/companyuser/controller/CompanyControllerIntegrationTest.java`

• Task 4.6: Company Controller & DTOs Implementation (GREEN Phase) **Task 4.6: Company Controller & DTOs Implementation (GREEN Phase)** (AC6, AC7)

  • Update @GetMapping("/{companyName}") Update `@GetMapping("/{companyName}")` to accept company name
  • Update CreateCompanyRequest Update `CreateCompanyRequest` DTO with validation annotations
  • Add @Pattern Add `@Pattern` validation for name field (alphanumeric, 12 chars)
  • Add displayName Add `displayName` field to request/response DTOs
  • Files:
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/controller/CompanyController.java
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/dto/CreateCompanyRequest.java
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/dto/CompanyResponse.java
  • Tests pass (GREEN)

# Phase 5: Backend - User Service

• Task 5.1: User Repository Methods (RED Phase) **Task 5.1: User Repository Methods (RED Phase)** (AC8, AC10)

  • Write failing test: Write failing test: `UserRepository.findByUsername(String username)`
  • Write failing test: Write failing test: `UserRepository.existsByUsername(String username)`
  • File: File: `services/company-user-management-service/src/test/java/ch/batbern/companyuser/repository/UserRepositoryTest.java`

• Task 5.2: User Repository Implementation (GREEN Phase) **Task 5.2: User Repository Implementation (GREEN Phase)** (AC8, AC10)

  • Add method: Add method: `Optional findByUsername(String username);`
  • Add method: Add method: `boolean existsByUsername(String username);`
  • File: File: `services/company-user-management-service/src/main/java/ch/batbern/companyuser/repository/UserRepository.java`
  • Tests pass (GREEN)

• Task 5.3: User Service Logic (RED Phase) **Task 5.3: User Service Logic (RED Phase)** (AC8, AC9, AC10)

  • Write failing test: create user auto-generates username
  • Write failing test: collision handling appends .2, Write failing test: collision handling appends `.2`, `.3`
  • Write failing test: update username with validation
  • Write failing test: custom username provided by user
  • File: File: `services/company-user-management-service/src/test/java/ch/batbern/companyuser/service/UserServiceTest.java`

• Task 5.4: User Service Implementation (GREEN Phase) **Task 5.4: User Service Implementation (GREEN Phase)** (AC8, AC9, AC10)

  • Inject SlugGenerationService into Inject `SlugGenerationService` into `UserService`
  • Implement username generation on create: Implement username generation on create: `slugService.generateUsername(first, last)`
  • Implement collision handling using Implement collision handling using `ensureUniqueUsername()`
  • Implement updateUsername() Implement `updateUsername()` method with validation
  • Update User entity: add username Update User entity: add `username` field
  • Files:
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/service/UserService.java
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/domain/User.java
  • Tests pass (GREEN)

• Task 5.5: User Controller & DTOs (RED Phase) **Task 5.5: User Controller & DTOs (RED Phase)** (AC9, AC11)

  • Write failing test: Write failing test: `GET /api/v1/users/{username}`
  • Write failing test: POST /api/v1/users Write failing test: `POST /api/v1/users` with optional username field
  • Write failing test: PATCH /api/v1/users/{username}/username Write failing test: `PATCH /api/v1/users/{username}/username` update endpoint
  • Write failing test: username validation error responses
  • File: File: `services/company-user-management-service/src/test/java/ch/batbern/companyuser/controller/UserControllerIntegrationTest.java`

• Task 5.6: User Controller & DTOs Implementation (GREEN Phase) **Task 5.6: User Controller & DTOs Implementation (GREEN Phase)** (AC9, AC11)

  • Update @GetMapping("/{username}") Update `@GetMapping("/{username}")` to accept username
  • Update CreateUserRequest DTO: add optional username Update `CreateUserRequest` DTO: add optional `username` field
  • Create UpdateUsernameRequest Create `UpdateUsernameRequest` DTO with validation
  • Create @PatchMapping("/{username}/username") Create `@PatchMapping("/{username}/username")` endpoint
  • Add username to UserResponse Add `username` to `UserResponse` DTO
  • Files:
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/controller/UserController.java
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/dto/CreateUserRequest.java
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/dto/UpdateUsernameRequest.java
    • services/company-user-management-service/src/main/java/ch/batbern/companyuser/dto/UserResponse.java
  • Tests pass (GREEN)

# Phase 6: Backend - Session Service

• Task 6.1: Session Repository & Service (RED Phase) **Task 6.1: Session Repository & Service (RED Phase)** (AC12)

  • Write failing test: Write failing test: `SessionRepository.findBySlugAndEventId(String slug, UUID eventId)`
  • Write failing test: Write failing test: `SessionRepository.existsBySlugAndEventId(String slug, UUID eventId)`
  • Write failing test: session slug generation from title
  • Write failing test: slug collision handling within event
  • Files:
    • services/event-management-service/src/test/java/ch/batbern/events/repository/SessionRepositoryTest.java
    • services/event-management-service/src/test/java/ch/batbern/events/service/SessionServiceTest.java

• Task 6.2: Session Repository & Service Implementation (GREEN Phase) **Task 6.2: Session Repository & Service Implementation (GREEN Phase)** (AC12)

  • Add repository methods for slug lookup
  • Implement slug generation on session create
  • Update Session entity: add slug Update Session entity: add `slug` field
  • Files:
    • services/event-management-service/src/main/java/ch/batbern/events/repository/SessionRepository.java
    • services/event-management-service/src/main/java/ch/batbern/events/service/SessionService.java
    • services/event-management-service/src/main/java/ch/batbern/events/domain/Session.java
  • Tests pass (GREEN)

# Phase 7: Frontend - Components

• Task 7.1: CompanyNameField Component (RED Phase) **Task 7.1: CompanyNameField Component (RED Phase)** (AC4, AC7)

  • Write failing test: renders with label and help text
  • Write failing test: validates 12 character limit
  • Write failing test: validates alphanumeric only
  • Write failing test: auto-sanitizes invalid characters
  • Write failing test: displays character count
  • File: File: `web-frontend/src/components/Company/CompanyNameField.test.tsx`

• Task 7.2: CompanyNameField Component Implementation (GREEN Phase) **Task 7.2: CompanyNameField Component Implementation (GREEN Phase)** (AC4, AC7)

  • Create component with Material-UI TextField
  • Implement real-time validation (max 12, alphanumeric)
  • Implement auto-sanitization on input change
  • Display character count: "8/12 characters"
  • Display help text with example: "Example: GoogleZH, UBS"
  • File: File: `web-frontend/src/components/Company/CompanyNameField.tsx`
  • Tests pass (GREEN)

• Task 7.3: UsernameField Component (RED Phase) **Task 7.3: UsernameField Component (RED Phase)** (AC9, AC10)

  • Write failing test: renders with auto-generated username
  • Write failing test: regenerate button calls onGenerate callback
  • Write failing test: validates username format
  • Write failing test: allows custom username input
  • Write failing test: displays collision error
  • File: File: `web-frontend/src/components/User/UsernameField.test.tsx`

• Task 7.4: UsernameField Component Implementation (GREEN Phase) **Task 7.4: UsernameField Component Implementation (GREEN Phase)** (AC9, AC10)

  • Create component with TextField + Refresh IconButton
  • Implement format validation (firstname.lastname pattern)
  • Implement regenerate button functionality
  • Display help text: "Used in profile URLs. Example: john.doe"
  • Show error for collision: "Username taken. Try john.doe.2"
  • File: File: `web-frontend/src/components/User/UsernameField.tsx`
  • Tests pass (GREEN)

# Phase 8: Frontend - API Services

• Task 8.1: Update API Services (RED Phase) **Task 8.1: Update API Services (RED Phase)** (AC2, AC6, AC9)

  • Write failing test: Write failing test: `eventsApi.getEvent("BATbern56")`
  • Write failing test: Write failing test: `companiesApi.getCompany("GoogleZH")`
  • Write failing test: Write failing test: `usersApi.getUser("john.doe")`
  • Write failing test: Write failing test: `usersApi.updateUsername("john.doe", "john.smith")`
  • Files:
    • web-frontend/src/services/api/eventsApi.test.ts
    • web-frontend/src/services/api/companiesApi.test.ts
    • web-frontend/src/services/api/usersApi.test.ts

• Task 8.2: API Services Implementation (GREEN Phase) **Task 8.2: API Services Implementation (GREEN Phase)** (AC2, AC6, AC9)

  • Update eventsApi.getEvent() Update `eventsApi.getEvent()` to use event code parameter
  • Update companiesApi.getCompany() Update `companiesApi.getCompany()` to use company name parameter
  • Update usersApi.getUser() Update `usersApi.getUser()` to use username parameter
  • Add usersApi.updateUsername() Add `usersApi.updateUsername()` method for PATCH endpoint
  • Update all API type definitions
  • Files:
    • web-frontend/src/services/api/eventsApi.ts
    • web-frontend/src/services/api/companiesApi.ts
    • web-frontend/src/services/api/usersApi.ts
    • web-frontend/src/types/api.ts
  • Tests pass (GREEN)

# Phase 9: Frontend - Routing

• Task 9.1: Update React Router Routes (RED Phase) **Task 9.1: Update React Router Routes (RED Phase)** (AC3, AC11)

  • Write failing test: navigate to /events/BATbern56 Write failing test: navigate to `/events/BATbern56` loads event
  • Write failing test: navigate to /companies/GoogleZH Write failing test: navigate to `/companies/GoogleZH` loads company
  • Write failing test: navigate to /users/john.doe Write failing test: navigate to `/users/john.doe` loads user
  • Write failing test: navigate to /speakers/john.doe Write failing test: navigate to `/speakers/john.doe` loads speaker view
  • File: File: `web-frontend/src/App.test.tsx`

• Task 9.2: React Router Implementation (GREEN Phase) **Task 9.2: React Router Implementation (GREEN Phase)** (AC3, AC11)

  • Update route: Update route: `} />`
  • Update route: Update route: `} />`
  • Update route: Update route: `} />`
  • Add route: Add route: `} />`
  • Add route: Add route: `} />`
  • File: File: `web-frontend/src/App.tsx`
  • Tests pass (GREEN)

# Phase 10: E2E Testing & Documentation

• Task 10.1: Create Bruno E2E Tests **Task 10.1: Create Bruno E2E Tests** (All ACs)

  • Create: Create: `bruno-tests/events-api/get-event-by-code.bru`
  • Create: Create: `bruno-tests/companies-api/get-company-by-name.bru`
  • Create: Create: `bruno-tests/users-api/get-user-by-username.bru`
  • Create: Create: `bruno-tests/users-api/update-username.bru`
  • Test event code URL pattern
  • Test company name URL pattern (case-insensitive)
  • Test username URL pattern
  • Test collision handling scenarios

• Task 10.2: Update OpenAPI Documentation **Task 10.2: Update OpenAPI Documentation**

  • Update Events API spec with eventCode Update Events API spec with `eventCode` path parameter
  • Update Companies API spec with companyName Update Companies API spec with `companyName` path parameter
  • Update Users API spec with username Update Users API spec with `username` path parameter
  • Add schema examples for all friendly ID types
  • Document error responses for invalid formats

• Task 10.3: Update Architecture Documentation **Task 10.3: Update Architecture Documentation**

  • Update 03-data-architecture.md Update `03-data-architecture.md` with new schema columns
  • Update 04-api-design.md Update `04-api-design.md` with friendly ID patterns
  • Create migration guide (if needed for future reference)

# Phase 11: Refactoring & Optimization (REFACTOR)

• Task 11.1: Backend Refactoring **Task 11.1: Backend Refactoring**

  • Extract ID resolution logic into utility methods
  • Add caching for friendly ID → UUID mappings (ElastiCache)
  • Optimize database queries (verify index usage)
  • Remove any test mocks from production code
  • Code cleanup and consistency

• Task 11.2: Frontend Refactoring **Task 11.2: Frontend Refactoring**

  • Extract common validation logic into hooks
  • Optimize component re-renders
  • Add loading states for ID resolution
  • Improve error messaging UX
  • Code cleanup and consistency

• Task 11.3: Performance Testing **Task 11.3: Performance Testing**

  • Benchmark friendly ID lookups vs UUID lookups
  • Verify index usage with EXPLAIN ANALYZE
  • Load test API endpoints with friendly IDs
  • Measure frontend bundle size impact

• Task 11.4: Final Verification **Task 11.4: Final Verification**

  • All 12 acceptance criteria verified in staging
  • All tests passing (unit, integration, E2E)
  • No mocks in production code
  • Documentation complete and accurate
  • Code review completed

# Dev Notes - Implementation Guide

# Service Setup

Directory Structure:

services/
├── event-management-service/
│   ├── src/main/java/ch/batbern/events/
│   │   ├── domain/Event.java (add eventCode field)
│   │   ├── domain/Session.java (add slug field)
│   │   ├── repository/EventRepository.java (add findByEventCode)
│   │   ├── repository/SessionRepository.java (add findBySlugAndEventId)
│   │   └── controller/EventController.java (update path params)
│   └── src/main/resources/db/migration/
│       ├── V20__add_event_code_column.sql
│       └── V23__add_session_slug.sql
│
├── company-user-management-service/
│   ├── src/main/java/ch/batbern/companyuser/
│   │   ├── domain/Company.java (add displayName field)
│   │   ├── domain/User.java (add username field)
│   │   ├── repository/CompanyRepository.java (add findByNameIgnoreCase)
│   │   ├── repository/UserRepository.java (add findByUsername)
│   │   ├── controller/CompanyController.java (update path params)
│   │   └── controller/UserController.java (update path params, add PATCH)
│   └── src/main/resources/db/migration/
│       ├── V21__add_company_display_name.sql
│       └── V22__add_user_username.sql
│
└── shared-kernel/
    ├── src/main/java/ch/batbern/shared/
    │   ├── types/EventId.java (add eventCode support)
    │   ├── types/CompanyId.java (add validation)
    │   ├── types/UserId.java (add username support)
    │   ├── types/SessionId.java (create new)
    │   └── service/SlugGenerationService.java (create new)
    └── src/test/java/ch/batbern/shared/
        ├── types/EventIdTest.java
        ├── types/CompanyIdTest.java
        ├── types/UserIdTest.java
        └── service/SlugGenerationServiceTest.java

Frontend Structure:

web-frontend/src/
├── components/
│   ├── Company/
│   │   ├── CompanyNameField.tsx (create new)
│   │   └── CompanyNameField.test.tsx (create new)
│   └── User/
│       ├── UsernameField.tsx (create new)
│       └── UsernameField.test.tsx (create new)
│
├── services/api/
│   ├── eventsApi.ts (update to use event codes)
│   ├── companiesApi.ts (update to use company names)
│   └── usersApi.ts (update to use usernames)
│
├── types/
│   └── api.ts (update type definitions)
│
└── App.tsx (update routes)

# Technical Design Notes

Slug Generation Algorithm:

private String slugify(String text) {
    return text.toLowerCase()
        // German characters
        .replaceAll("ä", "ae")
        .replaceAll("ö", "oe")
        .replaceAll("ü", "ue")
        .replaceAll("ß", "ss")
        // French characters
        .replaceAll("é", "e")
        .replaceAll("è", "e")
        .replaceAll("à", "a")
        .replaceAll("ê", "e")
        .replaceAll("ç", "c")
        // Remove diacritics
        .normalize("NFD")
        .replaceAll("\\p{M}", "")
        // Convert to URL-safe
        .replaceAll("[^a-z0-9]+", "-")
        .replaceAll("^-|-$", "")
        .substring(0, Math.min(text.length(), 100)); // Max 100 chars
}

Collision Handling Pattern:

private String ensureUniqueUsername(String baseUsername) {
    if (!userRepository.existsByUsername(baseUsername)) {
        return baseUsername;
    }

    // Find next available suffix
    int suffix = 2;
    while (userRepository.existsByUsername(baseUsername + "." + suffix)) {
        suffix++;
    }
    return baseUsername + "." + suffix;
}

ID Resolution Strategy:

// In controllers - accept both UUID and friendly ID
@GetMapping("/events/{idOrCode}")
public ResponseEntity<EventResponse> getEvent(@PathVariable String idOrCode) {
    Event event;

    if (isUUID(idOrCode)) {
        event = eventService.findById(UUID.fromString(idOrCode));
    } else {
        event = eventService.findByEventCode(idOrCode);
    }

    return ResponseEntity.ok(toResponse(event));
}

private boolean isUUID(String str) {
    try {
        UUID.fromString(str);
        return true;
    } catch (IllegalArgumentException e) {
        return false;
    }
}

# API Contracts

Events API:

paths:
  /api/v1/events/{eventCode}:
    get:
      summary: Get event by code
      parameters:
        - name: eventCode
          in: path
          required: true
          schema:
            type: string
            pattern: '^BATbern[0-9]+$'
            example: 'BATbern56'
      responses:
        '200':
          description: Event found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: 'Event not found: BATbern56'
                timestamp: '2025-01-15T10:30:00Z'
                status: 404

Companies API:

paths:
  /api/v1/companies/{companyName}:
    get:
      summary: Get company by name (case-insensitive)
      parameters:
        - name: companyName
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-zA-Z0-9]{1,12}$'
            example: 'GoogleZH'
      responses:
        '200':
          description: Company found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyResponse'

Users API:

paths:
  /api/v1/users/{username}:
    get:
      summary: Get user by username
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-z]+\.[a-z]+(\.[0-9]+)?$'
            example: 'john.doe'
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'

  /api/v1/users/{username}/username:
    patch:
      summary: Update username
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
            example: 'john.doe'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - newUsername
              properties:
                newUsername:
                  type: string
                  pattern: '^[a-z]+\.[a-z]+(\.[0-9]+)?$'
                  example: 'john.smith'
      responses:
        '200':
          description: Username updated successfully
        '409':
          description: Username already taken
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: 'Username already taken: john.smith. Try: john.smith.2'
                timestamp: '2025-01-15T10:30:00Z'
                status: 409

# Testing Requirements

Coverage Targets:

• Unit tests: >90% coverage
• Integration tests: >80% coverage
• E2E tests: All happy paths + critical error scenarios

Test Data Requirements:

// Event test data
EventTestDataBuilder.aEvent()
    .withEventNumber(56)
    .withEventCode("BATbern56")
    .build();

// Company test data
CompanyTestDataBuilder.aCompany()
    .withName("GoogleZH")
    .withDisplayName("Google Zürich AG")
    .build();

// User test data with collision
UserTestDataBuilder.aUser()
    .withName("Peter", "Müller")
    .withUsername("peter.mueller")
    .build();

UserTestDataBuilder.aUser()
    .withName("Peter", "Müller")
    .withUsername("peter.mueller.2") // Collision handling
    .build();

PostgreSQL Test Configuration:

@Testcontainers
@SpringBootTest
public abstract class AbstractIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
        .withDatabaseName("batbern_test")
        .withUsername("test")
        .withPassword("test")
        .withReuse(true); // Reuse container across tests for speed

    @DynamicPropertySource
    static void configureProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", postgres::getJdbcUrl);
        registry.add("spring.datasource.username", postgres::getUsername);
        registry.add("spring.datasource.password", postgres::getPassword);
        registry.add("spring.jpa.hibernate.ddl-auto", () -> "validate");
        registry.add("spring.flyway.enabled", () -> "true");
    }
}

# Definition of Done Checklist

# Development Complete

• All tests written BEFORE implementation (TDD followed)
• All 12 acceptance criteria have corresponding tests
• All 12 acceptance criteria implemented
• Unit tests written and passing (>90% coverage)
• Integration tests cover new functionality (>80% coverage)
• E2E tests pass for user journeys (Bruno tests)
• Code follows project conventions (Java, TypeScript, React)
• TypeScript types properly defined
• API documentation updated (OpenAPI specs)
• Database migrations created and tested (PostgreSQL)

# Schema Validation Complete

Migration Alignment:

• Task 2.1 completed: All migrations created (V20, V21, V22, V23)
• Migrations match architecture 100%
• Migrations tested with PostgreSQL (not H2)
• Unique indexes created and verified
• Check constraints validated

Entity Validation:

• JPA entities match migration schemas exactly
• All @Column names/types match architecture
• Integration tests validate entity-schema alignment

Documentation:

• Database Schema Reference section updated with migration versions

# Infrastructure Complete

• All infrastructure changes verified in CDK (if needed)
• API Gateway routes accept friendly IDs
• Database indexes created (event_code, company name, username, session slug)
• No new AWS resources required (uses existing RDS, API Gateway)

# Frontend Complete

• React components created: CompanyNameField, UsernameField
• Responsive design tested (mobile/tablet/desktop)
• Accessibility requirements met (WCAG 2.1 AA)
• Performance metrics achieved (no significant bundle size increase)
• Error handling and loading states implemented
• Internationalization support added (validation error messages)

# Review Ready

• PR created with detailed description
• Code review completed by team
• Security review passed (input validation, SQL injection prevention)
• Documentation updated:
  • README updated (if needed)
  • API docs updated (OpenAPI)
  • Architecture docs updated (03-data-architecture.md, 04-api-design.md)
• CLAUDE.md updated (if commands changed)
• Deployment instructions documented (migration order)

# Change Log

# Dev Agent Record

# Agent Model Used

To be filled by dev agent during implementation

# Implementation Approach

To be filled by dev agent during implementation

# Debug Log References

To be filled by dev agent during implementation

# Completion Notes

To be filled by dev agent during implementation

# Files Changed

To be filled by dev agent during implementation:

Created:

• List of new files

Modified:

• List of changed files

Deleted:

• List of removed files (if any)

# Deployment Notes

Migration Order:

1. Deploy database migrations (V20, V21, V22, V23)
2. Deploy backend services (all services simultaneously - greenfield)
3. Deploy frontend with updated routes
4. Verify all E2E tests pass in staging
5. Deploy to production

Rollback Procedure: Since this is greenfield (no existing data), rollback is straightforward:

1. Revert frontend deployment
2. Revert backend deployment
3. Rollback database migrations (if needed)

# QA Results

To be filled by QA Agent after implementation