BATbern Event Management Platform Architecture

# Overview

# Architecture Documentation Structure

The architecture documentation has been organized into 9 comprehensive sections that follow the C4 model progression and cover all aspects of the platform:

# Core Architecture Documents

1. 01-system-overview.md - System Context & High-Level Design

   • Project context and DDD approach
   • C4 model architecture diagrams
   • Component overview and relationships
   • Technical summary

2. 02-infrastructure-deployment.md - Infrastructure & Deployment

   • Deployment strategy and CI/CD pipelines
   • Infrastructure as code with DNS management
   • Monitoring and observability
   • Environment configurations

3. 03-data-architecture.md - Data Architecture

   • Domain data models and relationships
   • Database schemas per service
   • Data consistency patterns
   • Cross-service communication

4. 04-api-design.md - API Design & Workflows

   • REST API specifications
   • External API integrations
   • Core workflow patterns
   • API design principles

5. 05-frontend-architecture.md - Frontend Architecture

   • React component architecture
   • Role-adaptive UI patterns
   • State management and routing
   • Progressive Web App implementation

6. 06-backend-architecture.md - Backend Architecture

   • Service architecture patterns
   • Authentication and authorization
   • Comprehensive error handling
   • Resilience patterns (circuit breakers, retries)

7. 07-development-standards.md - Development Standards

   • Coding standards and naming conventions
   • Technology stack specifications
   • Source tree structure and organization
   • Development workflow and environment setup

8. 08-operations-security.md - Operations & Security

   • Security requirements and implementation
   • Performance benchmarks and SLAs
   • Accessibility implementation guidelines
   • Architect validation report

# Future Enhancement Documents

9. 09-aiml-architecture.md - AI/ML Architecture ⚠️ DEFERRED
   • Future AI/ML enhancement phases (OUT OF SCOPE FOR MVP)
   • Recommendation systems
   • Advanced analytics and insights

# Quick Navigation

# For Developers

• Getting Started: Start with 07-development-standards.md for setup and coding standards
• API Reference: See 04-api-design.md for complete API specifications
• Frontend Development: Check 05-frontend-architecture.md for React patterns
• Backend Development: Review 06-backend-architecture.md for service patterns

# For DevOps/Infrastructure

• Deployment: Reference 02-infrastructure-deployment.md
• Monitoring: See monitoring sections in 02-infrastructure-deployment.md
• Security: Check 08-operations-security.md

# For Product/Business

• System Overview: Start with 01-system-overview.md
• Data Models: Review 03-data-architecture.md for business entities
• Validation Report: See 08-operations-security.md for readiness assessment

# For Accessibility/Compliance

• Accessibility Guidelines: See 08-operations-security.md
• Performance Standards: Reference 08-operations-security.md
• Security Requirements: Check 08-operations-security.md

# Technology Versions

The platform maintains a single source of truth for all technology versions in versions.json. This file is automatically synchronized with actual dependency files to prevent documentation drift.

# Version Management

• 📋 Current Versions: See versions.json for exact technology versions
• 📝 Version Ranges: Architecture docs use major.x notation (e.g., 5.x = version 5.x+)
• 🔄 Automatic Sync: GitHub Actions automatically updates versions.json when dependencies change
• 🛠️ Manual Updates: Run node scripts/update-versions.js to manually sync versions
• ✅ CI Validation: Build pipeline checks for version drift between docs and dependencies

# Key Technologies

For detailed technology stack information, see tech-stack.md.

Current Major Versions:

• Frontend: React 19.x, TypeScript 5.x, MUI 7.x, Vite 7.x
• Backend: Java 21 LTS, Spring Boot 3.x, PostgreSQL 15+, Caffeine 3.x
• Infrastructure: AWS CDK 2.x, Single-AZ deployment (cost-optimized)
• Testing: JUnit 5.x, Vitest 3.x, Playwright 1.x, Testcontainers 1.x

# Key Architectural Decisions

# Architecture Decision Records (ADRs)

The architecture is governed by accepted ADRs in docs/architecture/ADR-*.md. Most-cited ADRs:

• ADR-002: Generic File Upload Service (presigned-URL pattern)
• ADR-003: Meaningful Identifiers in Public APIs (username, eventCode, companyName; no UUIDs in public APIs)
• ADR-004: Factor User Fields from Domain Entities (User is single source of truth for email, name, bio, photo, company)
• ADR-007: Unified User Profile (one User per person; no duplicate identity entities)
• ADR-009: Unified Speaker Workflow — single 8-state machine (IDENTIFIED → CONTACTED → READY → INVITED → ACCEPTED → CONTENT_SUBMITTED → QUALITY_REVIEWED + DECLINED), SPEAKER as a User role (no Speaker entity, no speakers table), standard Cognito with FORCE_CHANGE_PASSWORD on first login (no magic-link / dual-auth). Supersedes the legacy 10-state model and the magic-link auth stack. See ADR-009-unified-speaker-workflow.md and the implementation plan in docs/plans/speaker-workflow-refactor.md.
• ADR-010: Federated Identity via Cognito (Google SSO over OIDC) — delivered 2026-06-04 (Epic 12). Cognito as OIDC broker on the custom domain auth.batbern.ch (backend JWT contract unchanged), existing accounts link via AdminLinkProviderForUser in PreSignUp_ExternalProvider, new Google users auto-provision as ATTENDEE via canonical JIT and pass the ToS consent gate (Pattern C). Inactive-blocking moved to the API-Gateway is_active gate; companyId removed from the token (resolved via user-api). Runtime kill-switch: FEATURES_SSO_ENABLED. Deferred tail (backlog Story 12.10): Apple/generic OIDC + trigger-retirement cleanup to the target set PreSignUp, PreTokenGeneration, CustomEmailSender — PostConfirmation/PreAuthentication remain deployed until then. See ADR-010-federated-identity-via-cognito.md and the delivery record in docs/plans/sso-oidc-federation.md.

# Domain-Driven Design Approach

The platform employs a Domain-Driven Design microservices architecture with four distinct bounded contexts:

• Event Management Domain - Organizer workflows and automation
• Speaker Coordination Domain - Speaker portal and workflows
• Partner Analytics Domain - ROI tracking and strategic input
• Attendee Experience Domain - Content discovery and registration

# Technology Stack Summary

• Frontend: React 18.2+ with TypeScript, Material-UI, Zustand + React Query
• Backend: Java 21 LTS with Spring Boot 3.2+, PostgreSQL, Caffeine (in-memory caching)
• Infrastructure: AWS (ECS Fargate, Cognito, S3, CloudFront)
• Development: Gradle, Vite, GitHub Actions, AWS CDK

# Repository Structure

The platform uses a multi-repository approach for clear ownership and independent deployment:

BATbern-Platform/
├── shared-kernel/                 # Shared types, events, utilities
├── event-management-service/      # Organizer workflows & automation
├── speaker-coordination-service/  # Speaker portal & material collection
├── partner-coordination-service/  # Topic voting & meeting coordination
├── attendee-experience-service/   # Content discovery & registration
├── api-gateway/                   # Unified API entry point
├── web-frontend/                  # React frontend consuming all APIs
└── infrastructure/                # Shared infrastructure as code

# Change Log

This architecture document serves as the complete blueprint for the BATbern Event Management Platform, enabling the transformation from a static conference website into a comprehensive, enterprise-grade event management ecosystem serving Swiss IT professionals.