Guides & specifications

ADC (Atlanta Developers Conference) - Business Specifications

1. System Overview

Purpose

ADC is a conference management system for the Atlanta Developers Conference. It provides backend services to manage multi-day conference events, sessions, speakers, rooms, categories, and attendee feedback (question/answer surveys for events, sessions, and speakers). It supports user registration via email + password authentication (with optional MAUI device metadata) and integrates with the Sessionize platform to import conference schedule data (including speaker social links and questions).

Core Business Domains (organized by bounded context)

Conference (master schedule data — organizer-managed, Sessionize-imported):

• Event Management - Creating and managing conference events, rooms, sessions, and speakers
• Speaker & Category Management - Organizing speakers by categories (e.g., track, level, tags)
• Feedback Collection - Gathering attendee ratings and comments on events, individual sessions, and speakers
• External Data Sync - Importing conference data from Sessionize

Engagement (attendee-generated activity — user-facing):

• Personal Schedule - Attendee session bookmarking

Identity (identity and authentication):

• User Management - Email + password registration, JWT authentication, and role-based authorization

Key Capabilities

1. Full CRUD lifecycle for events, sessions, speakers, rooms, categories, and questions
2. Attendee survey/feedback submission scoped to the authenticated user (events, sessions, and speakers)
3. One-click data refresh from Sessionize to sync categories, speakers, rooms, sessions, and speaker social links
4. Paginated, filterable, sortable querying across all entities with lookup support
5. JWT-based email + password authentication for web and mobile attendees
6. Personal schedule builder with session bookmarking
7. Multi-day event support with per-event time zone configuration
8. Venue and room wayfinding information (floor, location, capacity, venue address, map URL)
9. Event publish/unpublish control for organizers
10. Room and session accessibility information for attendees with disabilities
11. Live stream and recording URLs for sessions
12. Plenum session designation for plenary/all-hands sessions
13. Top/featured speaker designation

2. Domain Model

Bounded Context: Conference

Event (Aggregate Root)

Relationships:

• Owns many Rooms (child entities)
• Owns many EventSpeakers (child join entities linking Event ↔ Speaker)
• Owns many EventQuestionAnswers (child feedback entities)
• Has many Sessions (associated by EventId)

Lifecycle: Created manually or seeded. May be refreshed from Sessionize when SessionizeCode is set.

Session (Aggregate Root)

Relationships:

• Belongs to one Event (required)
• May be assigned to one Room (optional)
• Owns many SessionSpeakers (child join entities linking Session ↔ Speaker)
• Owns many SessionQuestionAnswers (child feedback entities)
• Owns many SessionCategoryItems (child join entities linking Session ↔ CategoryItem)
• Referenced by many UserSessionBookmarks (Engagement context — own aggregate root)

Speaker (Aggregate Root)

Relationships:

• Has many EventSpeakers (events the speaker participates in)
• Has many SessionSpeakers (sessions the speaker presents)
• Owns many SpeakerCategoryItems (child join entities linking Speaker ↔ CategoryItem)
• Owns many SpeakerQuestionAnswers (child feedback entities for speaker-level survey responses)
• May be linked to one User (via LinkedUserId — 1:1, see Section 12.4)

Lifecycle: Speaker.Create(id?, firstName, lastName, email?, bio?, tagLine?, profilePicture?, isTopSpeaker) sets core identity fields. Social links (TwitterHandle, LinkedInUrl, GitHubUrl, WebsiteUrl) and LinkedUserId are set only via Update() — they are not accepted at creation time. This reflects the typical flow: speakers are created during Sessionize import with basic profile data, and social links are populated in a subsequent update pass.

Category (Aggregate Root)

Relationships:

• Owns many CategoryItems (child entities — the values within this category)

Global scope warning: Categories are not scoped to a specific event (IR-5). All events share the same category pool. When multiple events use Sessionize import (UC-6), Sessionize-assigned Category and CategoryItem IDs (BR-61) must be consistent across all Sessionize sources. If two events import from different Sessionize instances that assign different meanings to the same category ID, the second refresh will overwrite the first event's category data (BR-48). This is acceptable for the current single-event-per-year model but becomes a data corruption risk if multiple concurrent events use independent Sessionize sources. See BR-74 for mitigation guidance.

CategoryItem

Relationships:

• Belongs to one Category (required)
• Has many SessionCategoryItems (sessions tagged with this item)
• Has many SpeakerCategoryItems (speakers tagged with this item)

Room

Relationships:

• Belongs to one Event (required)
• Has many Sessions (sessions scheduled in this room)

Question

Relationships:

• Has many EventQuestionAnswers
• Has many SessionQuestionAnswers
• Has many SpeakerQuestionAnswers

EventQuestionAnswer

Relationships:

• Belongs to one Event (required)
• Belongs to one Question (required)

Note: Exposes a computed QuestionType derived from the associated Question.

SessionQuestionAnswer

Relationships:

• Belongs to one Session (required)
• Belongs to one Question (required)

Note: Exposes a computed QuestionType derived from the associated Question.

Join Entity Convention: All join entities below are pure association records with no business attributes beyond their foreign keys. They support add and delete only — update is not meaningful when there are no mutable attributes. To change an association, delete and re-create it.

EventSpeaker (Join Entity)

Links a Speaker to an Event.

SessionSpeaker (Join Entity)

Links a Speaker to a Session.

SessionCategoryItem (Join Entity)

Links a Session to a CategoryItem (tag/classification).

SpeakerCategoryItem (Join Entity)

Links a Speaker to a CategoryItem (tag/classification).

SpeakerQuestionAnswer

Relationships:

• Belongs to one Speaker (required)
• Belongs to one Question (required)

Note: Exposes a computed QuestionType derived from the associated Question. Speaker-level feedback enables attendees to rate and comment on individual speakers independently of specific sessions.

Bounded Context: Engagement

Design rationale: Engagement entities are separated from Conference because they have fundamentally different write profiles. Conference data is organizer-managed and low-write (imported from Sessionize, edited by organizers). Engagement data is attendee-generated and high-write (hundreds of users bookmarking during a live session). Mixing them in one bounded context would create aggregate contention.

UserSessionBookmark (Aggregate Root)

Relationships:

• References one User (required)
• References one Session (required)

Business Rules: BR-21 (unique per user+session), BR-22 (informational only)

• The session's EventId is not denormalized onto the bookmark — it is derived from Session.EventId when needed via a join, avoiding inconsistency if a session were reassigned

Bounded Context: Identity

User (Aggregate Root)

Relationships:

• Referenced by many UserSessionBookmarks (Engagement context)
• May be linked to one Speaker (via LinkedSpeakerId — 1:1, see Section 12.4)

Lookup capabilities: Users can be found by Email (unique lookup).

Why User has no owned children: Attendee-generated content (bookmarks) lives in the Engagement context as standalone aggregate roots. They reference User but are not managed through the User aggregate.

Cross-Cutting: Auditable Entities

Every entity in the system tracks:

Value Objects

3. Business Rules

Explicit Rules

Reading guide: Some rules reference other rules defined later in the document (e.g., BR-63, BR-80 are defined in Section 10). Forward references use the BR-* numbering consistently — search for the number to find the full definition.

Numbering convention: Business rule numbers (BR-*) are not sequential. Rules are numbered in the order they were identified during iterative specification development. Gaps (e.g., BR-23 through BR-40 do not exist) and out-of-sequence additions (e.g., BR-127 was added after BR-129) are intentional — renumbering would break cross-references throughout the document. Rules numbered BR-200+ are grouped in Section 12 (Authentication & Identity Architecture) and address the email-based identity model.

Inferred Rules

4. Use Cases / Business Processes

UC-1: User Registration & Login

See UC-30 (Registration) and UC-31 (Login) in Section 12.2 for the current email + password authentication flows.

UC-2: Browse Events

Actors: Attendee, API consumer Preconditions: None (read endpoints do not require auth)

Main Flow:

1. Consumer requests list of events (with optional pagination, filtering, sorting)
2. System returns only published events for unauthenticated/attendee users (BR-108). Organizers also see unpublished events.
3. Response includes child data if requested (rooms, sessions, speakers, question answers)

Alternate Flows:

• Request a single event by ID
• Request events in lookup format (Id + Name pairs) for dropdown population — see section 11.7 for the lookup endpoint contract
• Request with includeChildren=true to get nested child entities (one level only, per BR-80)
• Filter by IsPublished to find published events

Business Rules: BR-43, BR-108

UC-3: Browse Sessions

Actors: Attendee Preconditions: Events exist in the system

Main Flow:

1. Consumer requests sessions with optional filtering/sorting
2. Sessions can be filtered by EventName or RoomName (mapped to navigation properties)
3. System returns sessions with optional children (speakers, category items, question answers)

UC-4: Submit Event Feedback

Actors: Authenticated attendee Preconditions: User is authenticated; Event exists and is Published (BR-108); Questions exist for QuestionEntity = "Event"

Main Flow:

1. Attendee submits feedback per-question via standard CRUD on EventQuestionAnswer (BR-107)
2. System validates each AnswerValue against the question's QuestionType (BR-124)
3. Each answer is associated with the event and question, with CreatedBy set to the current user ID
4. If the user has previously submitted an answer for the same (QuestionId, EventId), the existing answer is overwritten (BR-123)

Business Rule: Users can only view their own event feedback (BR-8). BR-107 (per-question submission).

UC-5: Submit Session Feedback

Actors: Authenticated attendee Preconditions: User is authenticated; Session and Questions exist; Session is not a service session (BR-91); Session status is Accepted or null (BR-49); Session's parent Event is Published (BR-108)

Main Flow:

1. Attendee submits feedback per-question via standard CRUD on SessionQuestionAnswer (BR-107)
2. System validates that the session is not a service session (BR-91) and has an eligible status — Accepted or null (BR-49)
3. System validates each AnswerValue against the question's QuestionType (BR-124)
4. Each answer is associated with the session and question, with CreatedBy set to the current user ID
5. If the user has previously submitted an answer for the same (QuestionId, SessionId), the existing answer is overwritten (BR-123)

Business Rule: Users can only view their own session feedback (BR-9). BR-107 (per-question submission).

UC-6: Refresh Event Data from Sessionize

Actors: Organizer (via API call) Preconditions: Event exists with a valid SessionizeCode; user has the Organizer role (BR-41)

Main Flow:

1. Organizer triggers refresh for a specific event (POST /api/events/{id}/refresh). This is a POST because it mutates server state (upserts entities); GET is not appropriate for write operations.
2. System checks the per-event throttle (BR-63) — if a refresh occurred within the last 5 minutes, returns HTTP 429 with Retry-After header
3. System retrieves the event and verifies it has a SessionizeCode (BR-6)
4. System calls the Sessionize "View All" API endpoint
5. System synchronizes data in order: a. Categories and CategoryItems — upsert (add if new, update if existing) b. Questions — upsert questions from Sessionize with QuestionSource = "Sessionize" (question definitions with text, type, and entity target) c. Rooms — upsert d. Speakers — upsert speakers (including social links: TwitterHandle, LinkedInUrl, GitHubUrl, WebsiteUrl, and IsTopSpeaker flag), create EventSpeaker links if not already linked, assign SpeakerCategoryItems, import SpeakerQuestionAnswers e. Sessions — upsert sessions (including IsServiceSession, IsPlenumSession, LiveUrl, RecordingUrl from Sessionize), create SessionSpeaker and SessionCategoryItem links
6. System updates Event.LastSessionizeRefreshOn and Event.LastSessionizeRefreshBy
7. All changes are persisted transactionally

Alternate Flows:

• If SessionizeCode is blank, returns HTTP 400 with detail "Event has no SessionizeCode configured"
• If the Sessionize API is unreachable (timeout, HTTP 5xx, DNS failure), returns HTTP 502 Bad Gateway with detail "Sessionize API is unavailable. Try again later." No partial data is persisted — the transaction is rolled back.
• If the Sessionize API returns an empty or null response, returns HTTP 200 with a response body indicating zero entities synced (not an error — the Sessionize event may have no data yet)

Important: Sessionize refresh only syncs Conference master data (categories, questions, rooms, speakers, sessions). User-generated data — EventQuestionAnswers, SessionQuestionAnswers, SpeakerQuestionAnswers, and UserSessionBookmarks — is never modified by a Sessionize refresh. Locally soft-deleted entities (BR-136) are skipped during refresh.

Postconditions: Local data reflects the current state of the Sessionize schedule.

Response body (POST /api/events/{id}/refresh, HTTP 200):

{
            "categoriesSynced": 5,
            "categoryItemsSynced": 18,
            "questionsSynced": 6,
            "roomsSynced": 8,
            "speakersSynced": 42,
            "sessionsSynced": 35,
            "skippedSoftDeleted": 2,
            "warnings": [
              "Session 'Lightning Talk X' has zero duration (StartsAt equals EndsAt) — stored as-is per BR-122",
              "Skipped 2 soft-deleted entities present in Sessionize response (BR-136)"
            ]
          }

• *Synced counts reflect total entities created or updated (not just new ones)
• skippedSoftDeleted counts entities present in Sessionize response but skipped because they are locally soft-deleted (BR-136)
• warnings lists non-fatal issues encountered during import (e.g., BR-122 duration violations, BR-136 soft-deleted skips). Empty array when no warnings.

UC-7: Manage Event Rooms

Actors: Organizer Preconditions: Event exists; user has the Organizer role (BR-41)

Main Flow:

1. Add a room to an event: system validates the room's EventId matches the parent event (BR-2), adds the room, raises RoomChanged domain event
2. Update a room: system locates the room by ID within the event's collection, replaces it (BR-4)
3. Delete a room: system soft-deletes the room (BR-1, BR-5)

UC-8: Manage Categories and Category Items

Actors: Organizer Preconditions: User has the Organizer role (BR-41); Category must exist for items

Main Flow:

1. Create a category with title, sort order, and optional type
2. Add category items (values) to the category
3. Add, update, or delete category items within the category

UC-9: Manage Speaker Category Assignments

Actors: Organizer Preconditions: User has the Organizer role (BR-41); Speaker and CategoryItem exist

Main Flow:

1. Assign a category item to a speaker via the Speaker aggregate
2. System validates the speaker exists and assigns the category item

UC-10: View User Claims

Actors: Authenticated attendee Preconditions: Valid JWT token

Main Flow:

1. Attendee calls GET /api/userclaims
2. System returns all claims embedded in the JWT (user_id, email, role, first_name, last_name, and optionally speaker_id)

UC-11: Manage Personal Schedule (Session Bookmarks)

Actors: Authenticated attendee Preconditions: User is authenticated; Sessions exist

Main Flow:

1. Attendee browses sessions (UC-3)
2. Attendee bookmarks a session (POST /api/bookmarks with UserId and SessionId)
3. System creates a UserSessionBookmark record (standalone aggregate root — not through the User aggregate)
4. Attendee views their personal schedule (GET /api/bookmarks?userId={userId}) — returns bookmarked sessions in chronological order

Alternate Flows:

• Attendee removes a bookmark (DELETE /api/bookmarks/{bookmarkId})
• Attendee retrieves bookmarked session IDs for quick lookup (GET /api/bookmarks/session-ids?userId={userId}) — returns a dictionary of SessionId → BookmarkId for efficient UI rendering (e.g., toggle bookmark buttons)
• Attempting to bookmark the same session twice returns a conflict/duplicate error
• Attempting to bookmark a service session (IsServiceSession = true) returns HTTP 400 (BR-91)
• Attempting to bookmark a session with non-eligible status (anything other than Accepted or null) returns HTTP 400 (BR-49)
• Re-bookmarking a previously removed (soft-deleted) bookmark reactivates the existing record rather than creating a new one (BR-135)

Postconditions: User's personal schedule is updated.

Business Rules: BR-21, BR-22, BR-49, BR-91, BR-135

UC-19: Manage Conference Entities (Standard CRUD)

Actors: Organizer Preconditions: User has the Organizer role (BR-41)

Scope: This use case covers the standard create, update, and delete operations for Conference aggregate roots — Event, Session, Speaker, and Question — and their child entities managed through the parent aggregate. Read operations are public (BR-43).

Main Flow:

1. Organizer creates, updates, or deletes a Conference entity via the REST API
2. For aggregate roots: direct CRUD operations with soft delete (BR-1)
3. For child entities: operations routed through the parent aggregate — parent must exist (BR-3), child parent ID must match aggregate root ID (BR-2), child must exist for update (BR-4) or delete (BR-5)
4. Each mutation raises the appropriate domain event (see section 6)

Note: Operations with non-standard business logic are documented as individual use cases: room management (UC-7), category/item management (UC-8), speaker category assignments (UC-9), and Sessionize refresh (UC-6). The Actor-Action Matrix provides the complete enumeration of all actions.

Business Rules: BR-1 through BR-5, BR-10, BR-41

UC-21: Delete User Account

Actors: Authenticated attendee (own account), Organizer (any account) Preconditions: User is authenticated; target User exists

Main Flow:

1. Attendee requests account deletion (DELETE /api/users/{userId})
2. System verifies the requesting user is either the account owner or has the Organizer role
3. System soft-deletes the User record (BR-1, BR-56)

Alternate Flows:

• Non-owner, non-organizer attempts deletion — system returns HTTP 403
• User does not exist — system returns HTTP 404
• User is already soft-deleted — system returns HTTP 200 (idempotent)

Postconditions: User can no longer authenticate.

Business Rules: BR-1, BR-56

Actor-Action Matrix

This section maps every action in the system to the actor(s) that can perform it. Actions include formal use cases (UC-*), implicit CRUD from Key Capability #1, and capabilities mentioned in UC postconditions or business rules.

Actors

API Consumer (Unauthenticated)

Attendee (Authenticated, role: Attendee)

All API Consumer actions, plus:

Authentication & Identity:

Feedback (Conference context, attendee-written):

Personal Schedule (Engagement context):

Account Management:

Speaker (Attendee with speaker_id claim)

All Attendee actions, plus:

Note: Actions 90 and 91 are technically accessible to all actors (including unauthenticated API Consumers) because the endpoints use AllowAnonymous. They are listed here because the feature was designed for speaker self-service and the {speakerId} parameter refers to the speaker's own data. Any authenticated user or API consumer can call these endpoints for any speaker.

Organizer (role: Organizer)

All Attendee actions, plus:

Event (aggregate root) CRUD:

Session (aggregate root) CRUD:

Speaker (aggregate root) CRUD:

Category (aggregate root) CRUD:

Question (aggregate root) CRUD:

Child entity management (through parent aggregate):

Endpoint convention: Child entity write endpoints use top-level routes (e.g., /api/rooms, not /api/events/{eventId}/rooms). The parent aggregate ID is included in the request body and validated via BR-2 (child's parent ID must match the aggregate root ID). Read endpoints for all child entities also use top-level routes (see Section 11.3).

Note: Join entities (EventSpeaker, SessionSpeaker, SessionCategoryItem, SpeakerCategoryItem) have no update action — they have no mutable attributes beyond foreign keys. CategoryItem retains update because it has mutable fields (Name, Sort).

Sessionize integration:

User management:

Speaker linking:

Event lifecycle:

System (Non-Human)

Actions initiated autonomously by domain event handlers after persistence:

Action Count Summary

5. Workflows & State Transitions

Session Status

The Session.Status field is a free-text string imported from Sessionize. Default: null (for manually created sessions). Known Sessionize values: Accepted, Waitlisted, Accept Queue, Nominated, Decline Queue, Declined. No state machine is enforced — the status is stored as-is from the external system. Only Accepted and null statuses are eligible for public display, bookmarking, and feedback. All other statuses (including unknown values) are excluded from public views and engagement actions (BR-49).

Session Confirmation Workflow

Note: These are boolean flags set during Sessionize import. No state-machine transition enforcement exists — they are informational fields.

Entity Lifecycle States (DomainEntityState)

Used in domain events to indicate what happened to a child entity:

Event Lifecycle

Unpublished (default, IsPublished = false)
            → Published (IsPublished = true, visible to all users, engagement enabled)
            → Unpublished (IsPublished = false, hidden from public endpoints)

Unpublished events and their sessions are visible only to organizers. Publishing an event makes it and its sessions visible to all users via public endpoints.

Soft Delete Lifecycle

All entities follow: Active → (Delete action) → Soft-Deleted (IsDeleted = true)

Soft-deleted records are automatically excluded from all normal queries.

6. Events & Side Effects

Domain Events

Domain events are raised for entity mutations. Not all events have registered handlers — events without handlers serve as extension points for future requirements.

Event Handlers & Side Effects

Note: Only RoomChanged, SessionCreated, and SpeakerChanged (Deleted) currently have registered handlers. All three perform logging or link cleanup. The remaining domain events (including UserRegistered, UserPasswordChanged, UserDeleted, SpeakerQuestionAnswerChanged, and others) are defined but have no handlers — they exist as extension points and will gain handlers when concrete requirements emerge (e.g., real-time notifications, audit logging, analytics, engagement analytics via UserSessionBookmarkChanged).

Dispatch Mechanism

Domain events are raised during entity mutations and dispatched asynchronously after changes are persisted.

7. Business Constraints & Invariants

Data Integrity

Cross-Entity Constraints

Temporal Constraints

8. External Integrations (Business Perspective)

Sessionize

Image Hosting

9. Glossary

DDD Structural Summary

Bounded Contexts

Aggregate Boundaries

Cross-Aggregate References

Design Decisions & Rationale

Why three bounded contexts instead of two:

The original Events + Identity split grouped all conference-related entities together regardless of write profile. Separating Engagement provides:

The primary benefit is conceptual separation — organizer-managed master data vs. attendee-generated activity — which keeps each module focused. The contention argument is secondary: Engagement aggregate roots are standalone (no parent to contend on), so the throughput benefit is about clean module boundaries rather than aggregate-level lock contention.

Why Engagement entities are standalone aggregate roots (not children of User or Session):

Child entity management through a parent aggregate loads the parent, performs the child action, then saves. This is correct for structural children (Room belongs to Event) where the parent enforces invariants. But for Engagement entities:

1. No parent invariant to enforce. "A user can only bookmark a session once" is a uniqueness constraint, not an aggregate invariant requiring the User or Session to validate.
2. Write contention. If 200 users bookmark the same session simultaneously, routing through the Session aggregate serializes all 200 writes through a single row.
3. Nested children unsupported. The single-level child entity management pattern does not support multi-level nesting.

Why EventQuestionAnswer and SessionQuestionAnswer remain in Conference as children of their aggregates:

This is a deliberate trade-off with known contention risk. Feedback writes are routed through the parent aggregate (Event or Session), meaning concurrent submissions load and save the parent.

The contention risk is real but bounded at the expected scale:

• Session feedback submissions tend to concentrate in the period after each session ends, producing a burst of 20–100 submissions in the first few minutes — not a gradual trickle. For a conference with a few hundred attendees, this burst is manageable: individual requests take milliseconds, and the database handles this concurrency without degradation.
• Event feedback is spread across the event's duration — minimal contention.
• The implementation must add child rows without locking or replacing the parent's entire child collection. Child entity additions should be append-only inserts keyed to the parent, not load-modify-save-all cycles.
• With last-write-wins semantics (BR-129), there is no risk of optimistic concurrency failures — only of two writes to the same unique key racing, which the upsert logic (BR-123) handles.

Feedback entities are the primary candidate for extraction to the Engagement context if attendee volume exceeds ~200 concurrent writers per session. EventQuestionAnswer, SessionQuestionAnswer, and SpeakerQuestionAnswer match the Engagement write profile on every dimension (attendee-generated, high-write during live events, real-time during sessions, eventual consistency acceptable) — the same rationale that justified separating UserSessionBookmark. They remain in Conference for v1 because the contention is bounded at current scale and the aggregate ownership simplifies transactional consistency. Extraction requires moving entities to standalone aggregate roots and adjusting DI — the domain model and API contract do not change.

Cross-aggregate validation for feedback submission (known hotspot):

Submitting a SessionQuestionAnswer (a child of the Session aggregate) requires validating state from three aggregates: (1) Session — exists, is not a service session (BR-91), status is Accepted or null (BR-49); (2) Event — is published (BR-108); (3) Question — exists, correct QuestionEntity (BR-128), QuestionType for answer validation (BR-124). EventQuestionAnswer similarly validates across Event and Question. SpeakerQuestionAnswer validates across Speaker and Question. This cross-aggregate read-on-write is intentional — the business rules genuinely require this validation and it cannot be decomposed further. The feedback services therefore depend on Event and Question read repositories in addition to their owning aggregate's repository. This is not accidental coupling; it is documented here so future developers understand why these service-layer dependencies exist and do not attempt to remove them in the name of aggregate isolation.

Why UserSessionBookmark does not store EventId:

A bookmark needs only UserId and SessionId. The Event is derivable from Session.EventId. Denormalizing EventId onto the bookmark is unnecessary because Session.EventId is immutable (BR-140) — there is no inconsistency risk. Queries that need to filter bookmarks by event join through Session — this is a read-path concern solvable by indexing, not a domain model concern.

Why bookmarks use soft-delete instead of hard-delete:

UserSessionBookmark follows the universal soft-delete pattern (BR-1) despite bookmarks having no historical reporting value. The rationale: (1) Consistency — every entity in the system uses soft-delete, eliminating special-case logic in the repository layer and keeping architecture tests simple. (2) Recovery — if a user accidentally removes a bookmark, the soft-deleted record could be restored (though no restore endpoint exists today). (3) Analytics — soft-deleted bookmarks provide engagement data (e.g., "how many users bookmarked then un-bookmarked this session"). The cost is minimal: soft-deleted bookmarks are excluded from queries and consume negligible storage.

Domain event dispatch:

Domain events are raised during entity mutations (e.g., adding a room to an event raises RoomChanged) and dispatched asynchronously after changes are persisted. Most domain events are produced and consumed within the Conference context. The exception is SpeakerChanged (Deleted), which is produced in the Conference context and consumed by a handler in the Identity context to clear the speaker-user link (BR-70). This is the only cross-context domain event handler — it replaces a direct cross-context write with an event-driven approach to maintain bounded context isolation. See Section 6 for the full list of domain events and their handlers.

Why Session is an aggregate root but cascade-deleted by Event (BR-127):

Session is an aggregate root because it independently owns children (SessionSpeakers, SessionQuestionAnswers, SessionCategoryItems) and is the target of cross-context references (UserSessionBookmark). It has its own lifecycle for scheduling, feedback, and bookmarking. However, when an Event is soft-deleted, orphaning its Sessions would create inconsistency — sessions with no parent event are meaningless. BR-127 introduces a pragmatic cross-aggregate cascade: Event deletion cascades to Sessions. This violates the strict DDD principle that aggregate roots are only deleted through their own boundary, but the alternative (requiring organizers to manually delete every session before deleting an event) is operationally impractical. The cascade is implemented at the service layer (not database-level), so domain events and child cascades (BR-55) fire correctly.

Why Organizers can submit feedback: Organizers inherit all Attendee capabilities, including feedback submission. This is intentional — conference organizers typically attend sessions. The Organizer role grants write access to all Conference entities, making it impossible to define "their" sessions vs. others'. Feedback is scoped to the authenticated user (BR-8, BR-9).

How role-based authorization works:

The system has two user roles — Attendee (default) and Organizer — stored on the User entity. At login (UC-31), the role is included as a role claim in the JWT. Authorization is enforced at three levels:

The Organizer role is the system's administrator role. Organizers manage all conference master data. Initial organizer accounts are created via database seeding (BR-45).

This design keeps the User entity simple (a single Role field rather than a many-to-many role table) because the conference domain has only two authorization tiers. If more granular roles were needed in the future (e.g., separate "Volunteer" or "Sponsor" roles), the field could be migrated to a role collection.

Why per-question feedback submission with POST-as-upsert:

Feedback answers are submitted individually via POST on EventQuestionAnswer and SessionQuestionAnswer endpoints. Unlike other entities where POST is create-only, feedback POST performs an upsert — it creates a new answer or overwrites an existing one for the same (CreatedBy, QuestionId, EntityId) key (BR-107, BR-123). This is a deliberate deviation from pure CRUD semantics that simplifies the client: attendees don't need to check whether they've already answered a question before submitting. The Question.IsRequired flag is advisory — clients should enforce it in the UI but the server does not validate completeness across all questions.

10. Specification Clarifications & Addenda

This section addresses gaps, ambiguities, and implicit design decisions identified during implementation review. New business rules are numbered BR-61+. API contract specifications are documented separately from business rules.

10.1 Sessionize Integration Clarifications

Entity ID Strategy (clarifies UC-6, BR-7)

The domain model does not explain how entities imported from Sessionize are matched to local records during upsert. The resolution:

Sessionize assigns stable IDs to each entity type — integers for Categories, CategoryItems, Rooms, and Sessions; GUIDs for Speakers. During import, the system uses these Sessionize-assigned IDs as the local primary key. ExistsAsync(sessionizeId) determines whether to create or update.

Removal Handling (clarifies BR-7)

BR-7 covers add and update but is silent on what happens when an entity exists locally but is absent from the Sessionize response (e.g., a speaker withdraws or a session is dropped).

Refresh Throttling

No constraint exists on how frequently an organizer can trigger a Sessionize refresh, risking excessive external API calls.

10.4 Speaker.Email Clarifications (clarifies Speaker entity)

The Speaker entity includes an Email property (imported from Sessionize), but uniqueness and visibility are not specified.

10.6 Rate Limiting Scope (clarifies BR-20)

BR-20 says 100 requests per minute "per client" without defining what "client" means.

10.8 Cascade Soft-Delete Behavior

BR-55 covers Session soft-delete and BR-56 covers User soft-delete, but the spec is silent on cascade behavior for Speaker, Category, Event, and Question soft-deletes.

Cascade rationale summary:

10.9 Question Scoping (clarifies Question entity)

Questions have no EventId — they are global. The spec does not address whether different events can have different survey questions.

10.10 includeChildren Depth (clarifies UC-2, UC-3)

The spec mentions includeChildren=true but does not define depth or scope per entity type.

Children per entity type:

Example: GET /api/events/{id}?includeChildren=true returns the event with its rooms, event-speakers, and event question answers. It does not include the event's sessions (which are a separate aggregate, queried via GET /api/sessions?filters[EventId].eq={id}).

Feedback scoping in includeChildren: When includeChildren=true returns EventQuestionAnswers (on Event) or SessionQuestionAnswers (on Session), the feedback records are scoped by the requester's role: Attendees see only their own answers (CreatedBy matches authenticated user). Organizers see all answers. Unauthenticated requests see no feedback answers — the feedback child collections are returned as empty arrays. This is consistent with BR-8 and BR-9.

10.14 Email Question Type Clarification (clarifies BR-50)

QuestionType: Email "collects contact information" but its purpose is unclear.

10.16 Time-Gated HTTP Status Correction

HTTP 403 ("Forbidden") should not be used for temporal constraint violations — those are client errors (bad request timing), not authorization failures.

10.17 Sort Tie-Breaking

Entity Sort fields (on Room, CategoryItem, Category, Question) have no specified behavior for ties.

10.19 Speaker.FullName Implementation

The Speaker entity includes FullName described as "Computed: {FirstName} {LastName}" without specifying the implementation.

Speaker.FullName is a read-only computed property — a C# property getter ($"{FirstName} {LastName}"), not a database column. It is serialized into DTOs and available for display. Because it has no database column, it cannot be used in database-level filtering or sorting. Clients that need to filter or sort by name should use FirstName or LastName.

10.20 Session DateTime Storage Format (clarifies Session entity, BR-87)

The spec states session times are "interpreted in the event's time zone" but does not specify the storage format.

Session.StartsAt and Session.EndsAt are stored as DateTime values representing local time in the event's configured time zone. They are not stored as UTC or DateTimeOffset. For server-side time comparisons (feedback availability), the current UTC time is converted to the event's time zone (via TimeZoneInfo.ConvertTimeFromUtc) before comparing against these values. This approach avoids timezone conversion complexity in queries and is appropriate because all sessions within an event share a single time zone (BR-87). The TimeZone field on Event is authoritative for interpreting these values.

10.21 Bookmark Reactivation After Soft-Delete (clarifies BR-21, BR-1)

BR-21 enforces bookmark uniqueness per (UserId, SessionId), and BR-1 requires soft delete. But the spec does not address what happens when a user re-bookmarks a session they previously un-bookmarked (soft-deleted).

10.22 Sessionize Refresh and Soft-Deleted Entities (clarifies BR-7, BR-48)

The spec does not define what happens when a Sessionize refresh includes an entity that has been locally soft-deleted.

10.23 QuestionType and QuestionEntity Immutability (clarifies Question entity, BR-50, BR-15)

The spec does not address what happens when a Question's QuestionType or QuestionEntity is changed after answers have been submitted.

10.24 CategoryItem Name Uniqueness (clarifies CategoryItem entity, BR-19)

The spec defines CategoryItem.Name as required (BR-19) but does not specify uniqueness within a Category.

10.24a Question ID Allocation for User-Created Questions (clarifies BR-61)

BR-61 states that Question IDs use ValueGeneratedNever — they are explicitly assigned, not database-auto-generated. Sessionize-imported questions receive their Sessionize-assigned ID. But the spec does not address how IDs are allocated for manually created questions (via POST /api/questions).

10.25 Engagement Context Implementation (clarifies DDD Structural Summary)

The DDD Structural Summary defines three bounded contexts (Conference, Engagement, Identity). The Engagement context is implemented as a standalone module at Source/Modules/Engagement/.

Implementation note: The Engagement bounded context (currently containing UserSessionBookmark) is implemented as a dedicated module (MMCA.ADC.Modules.Engagement) with its own Domain, Application, Infrastructure, API, and Shared layers. This provides clean bounded context separation and positions the module for future expansion (e.g., attendee preferences, session check-ins).

10.26 Logout/Revoke Endpoint (clarifies BR-216)

BR-216 describes logout behavior but no use case or endpoint is specified.

Endpoint: POST /auth/revoke

Authentication: Required

Request body: None.

Main Flow:

1. System revokes the authenticated user's refresh token (marks as invalidated).
2. For web clients: the HttpOnly cookie is cleared in the response.
3. For MAUI clients: no server-side action is needed beyond token revocation — the client clears stored credentials from SecureStorage locally.
4. Returns HTTP 204 No Content.

Response codes:

• HTTP 204 — token revoked successfully (idempotent — returns 204 even if no active refresh token exists)
• HTTP 401 — not authenticated

Note: Access tokens cannot be server-side invalidated before expiry (BR-216). After logout, the access token remains valid until its 1-hour TTL expires. For security-critical scenarios (account compromise), the soft-deleted user JWT check (BR-133) provides a fallback — soft-deleting the account immediately blocks all requests.

10.27 Existing Bookmarks on Session Status Change (clarifies BR-49, BR-21)

BR-49 prevents creating bookmarks for sessions with non-eligible statuses, but does not address existing bookmarks when a session's status changes after bookmarking.

10.28 Session.EventId Immutability (clarifies Session entity)

The spec does not address whether a Session's EventId can be changed after creation.

10.29 SpeakerQuestionAnswer API Gap (implementation status)

The domain model supports SpeakerQuestionAnswer as a child entity of the Speaker aggregate (with AddSpeakerQuestionAnswer, UpdateSpeakerQuestionAnswer, RemoveSpeakerQuestionAnswer methods). BR-107 mentions SpeakerQuestionAnswer alongside EventQuestionAnswer and SessionQuestionAnswer as a feedback submission mechanism.

However, no SpeakerQuestionAnswersController exists — SpeakerQuestionAnswer CRUD is not exposed via REST API. Speaker question answers are currently populated only through Sessionize import (UC-6, which imports speaker survey responses from Sessionize). Manual speaker feedback submission by attendees is not yet available.

Impact: Actor-Action Matrix items 73a–73c (speaker question answer management) describe domain-layer capabilities that are not yet exposed as API endpoints. Attendees cannot submit speaker-level feedback through the API. This is a known gap — the domain is ready, but the API controller has not been implemented.

To implement: Create a SpeakerQuestionAnswersController following the same pattern as EventQuestionAnswersController and SessionQuestionAnswersController. The controller should use RequireAuthenticated authorization (matching the feedback pattern), apply user-scoping for reads (attendees see own answers only), and enforce BR-128 (QuestionEntity = "Speaker") and BR-124 (answer validation) on submission.

11. API Contract Specifications

This section documents API design decisions that apply across all endpoints.

11.1 Error Response Format

All error responses use the RFC 9457 ProblemDetails format (the successor to RFC 7807, same structure):

{
            "type": "https://tools.ietf.org/html/rfc9457",
            "title": "Business rule violation",
            "status": 400,
            "detail": "A user can bookmark a session only once."
          }

Validation errors (422) include a field-level errors dictionary:

{
            "type": "https://tools.ietf.org/html/rfc9457",
            "title": "Validation failed",
            "status": 422,
            "errors": {
              "Title": ["'Title' must not be empty."],
              "StartsAt": ["'StartsAt' must be before 'EndsAt'."]
            }
          }

Environment behavior: In development, the detail field includes the full exception message and stack trace. In production, business rule violations (DomainException) include the rule message; unhandled exceptions return a generic message with no internal details.

11.2 Pagination Response Contract (clarifies BR-11, BR-18)

Paginated endpoints (GET with pageNumber and pageSize parameters) return:

Response body — PagedResult<T>:

{
            "items": [ ... ],
            "paginationMetadata": {
              "totalItemCount": 47,
              "pageSize": 10,
              "currentPage": 2,
              "totalPageCount": 5,
              "firstRowOnPage": 11,
              "lastRowOnPage": 20
            }
          }

Response header — X-Pagination contains the same PaginationMetadata object serialized as JSON, for clients that prefer reading metadata from headers.

Defaults and constraints:

• Default pageSize: 10
• Maximum pageSize: 500 (BR-11; values above 500 are silently capped)
• Page numbering is 1-based (pageNumber minimum: 1)
• TotalPageCount, FirstRowOnPage, and LastRowOnPage are computed server-side
• All PaginationMetadata values are non-negative (BR-18)

11.3 Filtering and Sorting

Filter syntax: Query parameters use the pattern filters[PropertyName].operator=value.

Supported filter operators:

Sorting: sortColumn specifies the property name; sortDirection is "asc" (default) or "desc". Only one sort column is supported per request. All filterable fields are also sortable. CreatedOn and LastModifiedOn are sortable on all entities.

Filterable fields per entity:

Note: Speaker.FullName and Session.Duration are computed properties with no database column and cannot be used for filtering or sorting. Clients should filter by FirstName/LastName or StartsAt/EndsAt instead.

Child entity read endpoints: Child entities (Room, CategoryItem, EventSpeaker, SessionSpeaker, etc.) have top-level read endpoints (GET /api/rooms, GET /api/categoryitems, etc.) even though they are owned children of their aggregate root. This is a deliberate pragmatic choice: read operations bypass aggregate boundaries for query convenience (e.g., listing all rooms across events, filtering category items by category). Write operations (create, update, delete) are always routed through the parent aggregate to enforce invariants (BR-2 through BR-5). This hybrid read-through/write-through-aggregate pattern is documented to avoid confusion with strict DDD aggregate boundaries.

11.4 Default Sort Orders

When no sortColumn is specified, entities are returned in the following default order:

11.5 Feedback Submission (BR-107)

Feedback answers are submitted via POST on the EventQuestionAnswer and SessionQuestionAnswer endpoints (SpeakerQuestionAnswer is a deferred capability: domain model only, no controller or UI; see §10.29 and BR-107). POST performs an upsert (see BR-107 for semantics).

Authentication: Required (BR-42)

Validation:

• QuestionId must reference an existing Question with the correct QuestionEntity — "Event" for EventQuestionAnswer, "Session" for SessionQuestionAnswer, "Speaker" for SpeakerQuestionAnswer (BR-128)
• AnswerValue is validated against QuestionType: Rating (integer 1–5), Text (max 2000 chars), Email (valid MailAddress format) — see BR-124
• Session feedback (both POST and PUT): session must not be a service session (BR-91)
• Event must be published (BR-108) — this applies to all users including Organizers. Feedback on unpublished events is rejected because the feedback flow assumes an event is live/accessible to attendees. Organizers who need to test feedback should publish the event first.
• Event must be published for session feedback too — SessionQuestionAnswer submission validates that the session's parent Event has IsPublished = true (BR-108). Submitting session feedback for a session belonging to an unpublished event returns HTTP 400 with detail "Feedback cannot be submitted for sessions in unpublished events."
• Session must have Status of Accepted or null (BR-49) — feedback is only accepted for sessions with eligible status

Upsert behavior: POST creates (HTTP 201) or overwrites (HTTP 200) based on the (CreatedBy, QuestionId, EntityId) uniqueness key (BR-123). PUT updates an existing answer by its ID (standard update). PUT on session feedback is subject to the same service session (BR-91), event visibility (BR-108), and session status (BR-49) constraints as POST.

Soft-deleted Question handling: If a Question referenced by a feedback answer is soft-deleted (BR-73), PUT on an existing answer that references that Question is still permitted — the answer retains its historical association. However, POST (new submission) referencing a soft-deleted Question is rejected with HTTP 422 ("Question not found or does not apply to this entity type") because soft-deleted questions are excluded from queries (BR-128 validation uses the active question set). This allows attendees to update previously submitted answers but not submit new answers to retired questions.

11.7 Lookup Endpoints

Lookup endpoints return lightweight Id + display name pairs for populating dropdowns, autocomplete, and reference selectors. Available on all aggregate root entities.

Endpoint pattern: GET /api/{entities}/lookup

Response body — array of LookupItem:

[
            { "id": 1, "name": "Atlanta Developers Conference 2025" },
            { "id": 2, "name": "Atlanta Developers Conference 2026" }
          ]

Lookup responses are not paginated — they return all non-deleted records. For entities with large cardinalities, prefer the paginated list endpoint with specific field filtering. Lookup responses respect event visibility (BR-108) — unpublished events are excluded for non-organizers.

11.8 includeChildren on List Endpoints

The includeChildren=true parameter is supported on both single-entity (GET /api/{entities}/{id}) and list (GET /api/{entities}) endpoints.

Performance consideration: When includeChildren=true is used on list endpoints, the implementation should apply a reduced page size cap (lower than the normal 500-item cap in BR-11) to limit query fan-out. The exact cap is an implementation concern. Clients that need large result sets should omit includeChildren and fetch child data separately.

Depth: One level only (BR-80). Children of children are never loaded.

11.9 Feedback Access

Organizers retrieve raw, individual feedback records via the standard paginated EventQuestionAnswer and SessionQuestionAnswer list endpoints (filtered by EventId/SessionId and QuestionId; the SpeakerQuestionAnswer endpoint is deferred with the rest of the speaker-feedback capability, see §10.29). Each record includes CreatedBy, AnswerValue, and timestamps.

12. Authentication & Identity Architecture

This section defines the authentication mechanism for both the Web UI (Blazor) and MAUI (mobile) clients, which share a common Razor class library. It replaces the device-based identity model with an email + password model and introduces speaker-user linking.

12.1 Identity Model

A user is uniquely identified by their email address. Each email corresponds to exactly one user account. This is the canonical identity across all platforms (web and mobile).

User Entity (detailed typing)

Note: The canonical User entity definition is in Section 2 (Bounded Context: Identity). The table below provides additional typing and constraint detail for implementation.

Evolution note: The original User entity used DeviceId as the primary identity (device-based registration). This was replaced with email + password authentication to support the web UI (Blazor). Email is now required and unique, PasswordHash/PasswordSalt/FirstName/LastName were added, DeviceId became optional metadata (changed from GUID to string), LinkedSpeakerId was added for speaker-user linking, and RefreshToken/RefreshTokenExpiry were added for web session management. The FullName computed property was added for display convenience. Domain events UserRegistered and UserPasswordChanged are raised for corresponding lifecycle actions.

Speaker Entity Addition

Note: LinkedUserId is also documented on the Speaker entity in Section 2.

12.2 Authentication Flows

UC-30: User Registration

Actors: Unauthenticated user (any platform) Preconditions: None (self-registration is open — BR-211)

Endpoint: POST /auth/register

Request body:

{
            "email": "attendee@example.com",
            "password": "SecureP@ss1",
            "firstName": "Alice",
            "lastName": "Smith",
            "deviceId": "a1b2c3d4-...",
            "deviceFormFactor": "phone",
            "devicePlatform": "iOS",
            "deviceModel": "iPhone 15",
            "deviceManufacturer": "Apple",
            "deviceName": "My iPhone",
            "deviceType": "Physical"
          }

Required fields: email, password, firstName, lastName Optional fields: All device fields (provided by MAUI clients only)

Main Flow:

1. System validates input (email format, password strength per BR-203, names not empty)
2. System checks that no user exists with the given email
3. System creates a new user record with hashed password (BR-204) and Role = Attendee (BR-45)
4. If device fields are provided (MAUI client), they are stored on the user record
5. System checks if a Speaker entity exists with Email matching the registered email (case-insensitive) — if match found and speaker is not already linked to a different user, sets User.LinkedSpeakerId and Speaker.LinkedUserId (BR-207)
6. System generates a JWT containing user_id, email, role, first_name, last_name, and optionally speaker_id claims
7. For web clients: system also generates a refresh token and sets it as an HttpOnly cookie (BR-205)
8. Returns access token response

Response body:

{
            "accessToken": "eyJhbGciOiJIUzI1NiIs...",
            "expiresIn": 3600,
            "tokenType": "Bearer"
          }

Response codes:

• HTTP 201 — user created, JWT returned
• HTTP 409 — email already registered
• HTTP 422 — validation failure (password too weak, invalid email format, missing required fields)

Alternate Flows:

• Email already registered → HTTP 409 Conflict with ProblemDetails: "An account with this email already exists."
• Password does not meet strength requirements → HTTP 422 with field-level validation errors

Postconditions: User has a valid account and JWT. If email matched a speaker, the speaker link is established.

UC-31: User Login

Actors: Registered user (any platform) Preconditions: User has a registered account

Endpoint: POST /auth/login

Request body:

{
            "email": "attendee@example.com",
            "password": "SecureP@ss1",
            "deviceId": "a1b2c3d4-...",
            "deviceFormFactor": "phone",
            "devicePlatform": "iOS",
            "deviceModel": "iPhone 15",
            "deviceManufacturer": "Apple",
            "deviceName": "My iPhone",
            "deviceType": "Physical"
          }

Required fields: email, password Optional fields: All device fields (provided by MAUI clients only)

Main Flow:

1. System validates email + password against stored credentials
2. If device fields are provided (MAUI client), system updates the device metadata on the user record
3. System checks speaker linking (in case a speaker was imported via Sessionize after the user registered) — same logic as registration step 5
4. System generates JWT with current claims
5. For web clients: generates refresh token, sets HttpOnly cookie
6. Returns access token response

Response body: Same shape as registration (accessToken, expiresIn, tokenType).

Response codes:

• HTTP 200 — login successful
• HTTP 401 — invalid email or password (generic message — do not reveal whether the email exists)
• HTTP 429 — too many failed attempts (BR-212)

Alternate Flows:

• Invalid credentials → HTTP 401 with ProblemDetails: "Invalid email or password." Failed attempt counter incremented (BR-212).
• Account soft-deleted → HTTP 401 (same generic message — soft-deleted accounts cannot authenticate)

Postconditions: User has a valid JWT. Device metadata updated if provided. Speaker link established if newly matched.

UC-32: Refresh Access Token (Web Only)

Actors: Authenticated web user Preconditions: Valid refresh token in HttpOnly cookie

Endpoint: POST /auth/refresh

Request body: The refresh token. Web clients send the token from the HttpOnly cookie; MAUI clients send stored credentials.

Main Flow:

1. System reads refresh token from cookie
2. System validates the token (not expired, not revoked)
3. System issues a new access token and rotates the refresh token (BR-205)
4. New refresh token is set as an HttpOnly cookie; old token is invalidated
5. Returns new access token

Response body: Same shape as login (accessToken, expiresIn, tokenType).

Response codes:

• HTTP 200 — new tokens issued
• HTTP 401 — refresh token invalid, expired, or revoked

Alternate Flows:

• Revoked token presented (reuse detection) → all refresh tokens for the user are revoked (BR-206). Returns HTTP 401. User must re-login.

MAUI clients do not use this endpoint. When a MAUI access token expires, the app re-authenticates silently by calling the login endpoint with credentials stored in SecureStorage. This provides equivalent UX (no user interaction) without refresh token complexity.

UC-33: Change Password

Actors: Authenticated user (any platform) Preconditions: User is authenticated with a valid JWT

Endpoint: PUT /auth/password

Request body:

{
            "currentPassword": "OldSecureP@ss1",
            "newPassword": "NewSecureP@ss2"
          }

Required fields: currentPassword, newPassword

Main Flow:

1. System validates the current password against stored credentials
2. System validates the new password meets strength requirements (BR-203)
3. System updates the password hash and salt
4. System raises UserPasswordChanged domain event
5. Returns HTTP 204 No Content

Response codes:

• HTTP 204 — password changed successfully
• HTTP 400 — current password incorrect
• HTTP 401 — not authenticated
• HTTP 422 — new password does not meet strength requirements (BR-203)

Postconditions: User's password is updated. Existing JWT remains valid until expiry. Refresh token is not invalidated — the user stays logged in.

12.3 Token Architecture

Access Token (JWT)

JWT Claims

Note: device_id is no longer a JWT claim. It is device metadata stored on the User entity, not an identity claim.

Refresh Token (Web Only)

12.4 Speaker-User Linking

Automatic Linking

Occurs at registration (UC-30 step 5) and login (UC-31 step 3):

1. System queries for a Speaker with Email matching User.Email (case-insensitive)
2. If a match is found and Speaker.LinkedUserId is null → link is established bidirectionally (User.LinkedSpeakerId = Speaker.Id, Speaker.LinkedUserId = User.Id)
3. If Speaker.LinkedUserId is already set to a different user → no automatic override (organizer must manually re-link)
4. JWT is issued with speaker_id claim when linked

Manual Linking (Organizer)

Manual linking overrides automatic linking (for cases where a speaker's Sessionize email differs from their user account email). Manual unlinking clears both sides of the relationship.

Speaker-Specific Features

When a user has a speaker_id claim, they gain access to read-only views of their own session data:

Authorization: The feedback and bookmark count endpoints are publicly accessible (AllowAnonymous) — any user (including unauthenticated API consumers) can view aggregated session feedback and bookmark counts for any speaker. This enables public speaker/session quality metrics. The profile update endpoint requires authentication: the requesting user's speaker_id JWT claim must match the {speakerId} in the URL, or the user must have the Organizer role.

Sessionize Conflict: When Sessionize data is refreshed (UC-6), speaker profiles are overwritten per BR-48 (Sessionize is the source of truth). Local edits made by a speaker via the app are replaced. This is consistent with existing behavior and keeps the import logic simple. Speakers should be informed that their profile edits may be overwritten during a Sessionize refresh.

Notification mechanism: When a speaker edits their profile via the app (BR-214), no real-time notification is sent to organizers. The edit is visible through the standard audit trail (LastModifiedBy, LastModifiedOn on the Speaker entity). Organizers can identify speaker-edited profiles by checking whether LastModifiedBy corresponds to the linked user rather than an organizer or the Sessionize refresh process. A dedicated notification (e.g., domain event, email alert) for speaker profile edits is a potential future enhancement but is out of scope for the initial implementation.

12.5 Shared Auth Layer (Common Razor Library)

The Web UI (Blazor) and MAUI UI share a common Razor class library for UI components. Authentication is abstracted through a shared interface with platform-specific implementations.

Auth Service Abstraction

IAuthenticationService
          ├── RegisterAsync(RegisterRequest, ipAddress?) → Result<AuthenticationResponse>
          ├── LoginAsync(LoginRequest) → Result<AuthenticationResponse>
          ├── RefreshTokenAsync(RefreshTokenRequest) → Result<AuthenticationResponse>
          ├── RevokeTokenAsync(userId) → Result
          ├── ChangePasswordAsync(userId, ChangePasswordRequest) → Result

The UI layer wraps this with platform-specific IAuthService implementations that add client-side concerns:

IAuthService (UI abstraction)
          ├── RegisterAsync(RegisterRequest) → AuthResult
          ├── LoginAsync(LoginRequest) → AuthResult
          ├── LogoutAsync() → void
          ├── RefreshTokenAsync() → AuthResult?
          ├── GetCurrentUserAsync() → UserClaims?
          ├── IsAuthenticatedAsync() → bool

AuthResult contains the access token, expiry, and parsed claims. UserClaims is a strongly-typed projection of the JWT claims (UserId, Email, Role, FirstName, LastName, SpeakerId?).

Platform Implementations

Blazor Integration

• Custom AuthenticationStateProvider wraps IAuthService
• CascadingAuthenticationState propagates claims to all Razor components
• AuthorizeView and [Authorize] attributes work identically on both platforms
• Role-based gating: <AuthorizeView Roles="Organizer"> for admin-only UI
• Speaker-specific UI gated on speaker_id claim presence

12.6 Business Rules

12.7 Password Management

Password change (UC-33) is supported via PUT /auth/password — authenticated users can change their own password by providing the current password and a new password.

Password reset via email is out of scope for the initial implementation. If an attendee forgets their password during the conference, they must contact an organizer to have their account deleted (UC-21) so they can re-register.

Rationale: The conference engagement window is 1–2 days. Re-registration is low-cost (bookmarks can be recreated in minutes). Adding password reset requires email sending infrastructure (SMTP/SendGrid) and a secure token flow, which is disproportionate to the benefit for v1.

Planned flow (when implemented):

1. POST /auth/forgot-password with { "email": "..." } → sends a reset code to the email (always returns HTTP 202 to prevent email enumeration)
2. POST /auth/reset-password with { "email": "...", "code": "...", "newPassword": "..." } → validates code, updates password

12.8 Design Rationale

Why email + password instead of device-based identity:

The original device-based registration model was designed for a mobile-only app where frictionless registration was paramount. With the addition of a web UI, device identity becomes untenable — browsers have no stable device identifier. Email is the natural cross-platform identity anchor: it works on both web and mobile, enables speaker linking (speakers already have email in Sessionize), and is familiar to all users.

Why email + password instead of magic link:

Magic link requires email delivery infrastructure for every login, not just for password resets. At a conference venue with spotty WiFi, waiting for an email to arrive is real friction. Email + password authentication works instantly once registered, requires no external email service for the core auth flow, and uses the same flow on both MAUI and web — simplifying the shared Razor library.

Why speaker is a claim, not a role:

Roles (Attendee, Organizer) are permission tiers — each tier unlocks a set of endpoints. Speaker is an identity link — it means "this user is the same person as this Speaker entity." A speaker is also an attendee (they attend sessions, give feedback, bookmark talks). A speaker could also be an organizer. Making speaker a role would create awkward combinations (Attendee+Speaker? Organizer+Speaker?) and conflate identity with authorization. Keeping it as a JWT claim is orthogonal to the role system.

Why refresh tokens for web but not MAUI:

MAUI can silently re-authenticate using credentials stored in SecureStorage — the user never sees a login prompt when their token expires. Web browsers have no equivalent secure credential store. A refresh token (7-day HttpOnly cookie) bridges this gap, keeping web users logged in for the conference duration without requiring email + password entry every hour.

Why DeviceId is retained as metadata:

Even though DeviceId is no longer used for authentication, it remains useful for: (a) analytics — understanding which devices attendees use, (b) future push notification targeting, and (c) debugging — correlating support requests with specific device configurations.