System Overview

This document outlines the complete fullstack architecture for BATbern Event Management Platform, including backend systems, frontend implementation, and their integration. It serves as the single source of truth for AI-driven development, ensuring consistency across the entire technology stack.

This unified approach combines what would traditionally be separate backend and frontend architecture documents, streamlining the development process for modern fullstack applications where these concerns are increasingly intertwined.

# Project Context

Project Nature: Revolutionary transformation from static Angular website to comprehensive event management platform Current State: Existing Angular codebase with 20+ years of historical event data Architecture Approach: Domain-Driven Design with Separate Bounded Contexts

Why DDD Enterprise Pattern is Superior:

1. Clear Domain Boundaries: The BATbern platform has distinct domains:

   • Event Management Domain (Organizer workflows)
   • Speaker Coordination Domain (Speaker portal & workflows)
   • Partner Analytics Domain (ROI tracking & strategic input)
   • Attendee Experience Domain (Content discovery & registration)

2. Enterprise Scalability: Each bounded context can:

   • Scale independently based on load (attendee domain vs organizer domain)
   • Deploy separately reducing deployment risk
   • Evolve at different paces (partner analytics may change more frequently)
   • Use appropriate technology per domain needs

3. Team Organization Benefits:

   • Different teams can own different domains
   • Reduces cognitive load per team
   • Clear API contracts between domains
   • Independent testing and deployment cycles

Repository Structure: DDD-Based Multi-Repository Approach

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

Benefits over Monorepo:

• Clear Ownership: Each service has dedicated team ownership
• Independent Deployment: Deploy speaker portal without affecting analytics
• Technology Flexibility: Java/Spring Boot for complex workflows, Node.js for content APIs
• Enterprise Governance: Easier compliance auditing per domain
• Fault Isolation: Issues in one domain don’t affect others

# Change Log

# Technical Summary

The BATbern Event Management Platform employs a Domain-Driven Design microservices architecture with four distinct bounded contexts, each deployed as independent services behind a unified API Gateway. The React-based frontend provides role-adaptive interfaces consuming domain-specific APIs, while shared infrastructure handles cross-cutting concerns like authentication, file storage, and monitoring. This architecture enables independent scaling and deployment of the complex workflow automation features (event management), high-volume content discovery (attendee experience), analytics-heavy partner services, and streamlined speaker coordination workflows. The design prioritizes enterprise-grade reliability, Swiss compliance requirements, and the ability to evolve each domain at different paces while maintaining cohesive user experiences across all four stakeholder groups.

# C4 Model Architecture Diagrams

# Level 1: System Context Diagram

# Level 2: Container Diagram (AWS-Optimized Architecture)

AWS Service Color Legend:

• 🟠 Orange (#FF9900): Compute/CDN (CloudFront, ECS, EventBridge)
• 🔴 Red/Pink (#DD344C, #FF4F8B): Security/Messaging (Cognito, SES, API Gateway)
• 🔵 Blue (#527FFF): Containers/Applications (ECS Fargate Services)
• 🟢 Green (#3F8624, #569A31): Database & Storage (RDS, S3)
• 🟣 Purple (#C925D1, #8C4FFF): Caching & DNS (Caffeine, Route53)

Note: This diagram uses AWS official color scheme. When AWS icons become stable in Mermaid, we can convert this to architecture-beta syntax with icon support.

Key Architecture Decisions:

1. Dual API Gateway: AWS HTTP API for edge security + Spring Boot Gateway for routing
2. ECS Fargate ARM64: 20% cost savings with Graviton2 processors
3. Single-AZ RDS: Cost-optimized for 1000 users/month workload
4. Application-level Caching: Caffeine in-memory per service instance (eliminates ElastiCache Redis, $149/month savings)
5. Branded CDN: Custom CloudFront domains (cdn.batbern.ch) for professional appearance
6. Event-Driven Architecture: EventBridge for loosely coupled domain events

Technology Stack:

• Frontend: React 18 + TypeScript, deployed on S3 + CloudFront
• API Gateway: Spring Boot 3 + Spring Cloud Gateway
• Microservices: Java 21 + Spring Boot, running on ECS Fargate
• Database: PostgreSQL 15 on RDS (ARM Graviton2)
• Authentication: AWS Cognito with OAuth2/JWT
• Storage: S3 with lifecycle policies
• Messaging: EventBridge for domain events

# Level 3: Component Diagram - Event Management Service

# Component Overview

# Event Management Service

Responsibility: Core event lifecycle management, organizer workflows, and automated event planning processes including the comprehensive 9-state workflow with slot management, quality control, overflow handling, and real-time collaboration.

Enhanced Workflow Components:

• Event Workflow State Machine - Manages 9-state progression from creation to archival (see 06a-workflow-state-machines.md)
• Slot Assignment Algorithm Service - Intelligent speaker-to-slot matching with preferences
• Quality Review Workflow Engine - Automated content validation and moderator review
• Overflow Management & Voting System - Organizer voting for speaker selection when capacity exceeded
• Real-time Notification & Escalation - Cross-stakeholder alerts and deadline management

Key Interfaces:

• /api/v1/events - Event CRUD operations and status management
• /api/v1/events/{id}/workflow - Enhanced 9-state workflow state management
• /api/v1/events/{id}/slots - Slot configuration and assignment management
• /api/v1/events/{id}/overflow - Speaker overflow voting and waitlist management
• /api/v1/events/{id}/timeline - Event timeline and milestone tracking
• /api/v1/organizers - Organizer role management and permissions

Dependencies:

• Speaker Coordination Service (enhanced speaker preferences and workflow states)
• Partner Coordination Service (partner topic voting integration)
• Quality Review Service (content validation and moderator workflows)
• Notification Service (real-time alerts and escalations)
• Shared Kernel (enhanced domain events, workflow types)
• AWS Cognito (organizer authentication)
• PostgreSQL (event data persistence with workflow state)
• Caffeine Cache (in-memory workflow state caching and optimization)

Technology Stack: Java 21 + Spring Boot 3.x, PostgreSQL 15+, Caffeine 3.x (in-memory caching), EventBridge (domain events), WebSocket (real-time notifications)

# Speaker Coordination Service

Responsibility: Enhanced speaker management with complex workflow states, slot preferences collection, material collection with quality control, and seamless coordination between organizers and speakers including waitlist management.

Enhanced Speaker Workflow Features (pre-ADR-009 description retained as historical context):

• Workflow State Management - 11-state progression with parallel paths: identified → contacted → ready → accepted/declined; then content_submitted → quality_reviewed ∥ slot_assigned → confirmed; plus overflow and withdrew states
• Slot Preferences Collection - Time slot preferences, technical requirements, accessibility needs
• Quality Review Integration - Abstract validation (1000 char limit), moderator review workflow
• Overflow Management - Separate tracking of overflow speakers with automatic promotion on dropouts

Key Interfaces:

• /api/v1/speakers - Enhanced speaker profile and expertise management
• /api/v1/speakers/{id}/preferences - Slot preferences and technical requirements
• /api/v1/sessions/{id}/quality-review - Content quality review workflow
• /api/v1/invitations - Speaker invitation workflow with enhanced context
• /api/v1/sessions/{id}/speakers - Speaker-session assignment with workflow states
• /api/v1/materials - Presentation material upload with quality validation

Dependencies:

• Event Management Service (enhanced session data and slot assignments)
• Company Management Service (speaker company relationships)
• Quality Review Service (content validation and moderator workflows)
• File Storage Service (presentation materials with versioning)
• Email Service (enhanced speaker communications and notifications)
• Notification Service (real-time speaker status updates)
• Shared Kernel (enhanced speaker domain events)

Technology Stack: Java 21 + Spring Boot 3.2, PostgreSQL, AWS S3 (file storage), SES (email notifications), WebSocket (real-time updates)

# Partner Coordination Service

Responsibility: Partner relationship management, strategic topic voting, partner meeting coordination, and partnership lifecycle management.

Key Interfaces:

• /api/v1/partners - Partner profile and relationship management
• /api/v1/partners/{id}/topic-votes - Strategic topic voting and suggestions
• /api/v1/partners/{id}/meetings - Partner meeting scheduling and coordination
• /api/v1/topics/voting - Topic voting and prioritization

Dependencies:

• Event Management Service (topic backlog integration, event participation data)
• Company Management Service (partner company data)
• Notification Service (meeting reminders and voting notifications)
• Shared Kernel (partner domain events)

Technology Stack: Java 21 + Spring Boot 3.2, PostgreSQL (partnership and voting data), AWS SES (meeting notifications)

# Attendee Experience Service

Responsibility: Attendee registration, content discovery, historical archive search, and personalized content recommendations across 20+ years of BATbern content.

Key Interfaces:

• /api/v1/events/{id}/registrations - Event registration management
• /api/v1/content/search - AI-powered content discovery
• /api/v1/attendees/me - Personal attendee dashboard
• /api/v1/recommendations - Personalized content recommendations

Dependencies:

• Event Management Service (event data for registration)
• Speaker Coordination Service (session and speaker data)
• Content Search Engine (PostgreSQL full-text search)
• Shared Kernel (attendee domain events)

Technology Stack: Java 21 + Spring Boot 3.2, PostgreSQL (registration data and content search)

# Company Management Service

Responsibility: Centralized company entity management with logo storage, partner recognition, and company creation workflows for speakers and organizers.

Key Interfaces:

• /api/v1/companies - Company CRUD operations and search
• /api/v1/companies/{id}/logo - Logo upload and management
• /api/v1/companies/suggest - Company name suggestions and duplicate detection

Dependencies:

• File Storage Service (logo management)
• All domain services (company relationship validation)
• Shared Kernel (company domain events)

Technology Stack: Java 21 + Spring Boot 3.x, PostgreSQL 15+, AWS S3 (logo storage), Caffeine 3.x (company search caching)

# Frontend Application

Responsibility: Role-adaptive user interface providing distinct experiences for organizers, speakers, partners, and attendees with Progressive Web App capabilities.

Key Interfaces:

• Role-based component rendering system
• API client service layer
• State management for user sessions
• PWA service worker for offline capabilities

Dependencies:

• API Gateway (all backend communication)
• CDN (static asset delivery)
• Browser APIs (PWA features)

Technology Stack: React 18.2 + TypeScript, Zustand (state management), React Query (server state), Vite (build tool), Workbox (PWA)