SpecKit Ticketing Platform is a distributed SaaS platform for selling event tickets, designed with enterprise-grade architecture patterns including Hexagonal Architecture , CQRS (Command Query Responsibility Segregation) , and an Event-Driven approach. The system guarantees consistency and high availability through distributed locks and asynchronous messaging.
Built on .NET 9 with a modern microservices architecture, SpecKit demonstrates how to build scalable, maintainable systems that handle high-concurrency scenarios like ticket sales where race conditions must be prevented.
This platform is designed for learning and training purposes , showcasing real-world architectural patterns in a practical context. All configuration is pre-loaded in docker-compose.yml and appsettings.json for immediate deployment without manual setup.
Key Features Distributed Microservices Architecture The platform consists of independent, specialized services that communicate through both synchronous and asynchronous channels:
Catalog Service - Event and venue management with seat map queriesInventory Service - Seat reservation with distributed locking and TTL managementOrdering Service - Shopping cart and order lifecycle managementPayment Service - Payment processing (simulated for MVP, extensible for real providers)Fulfillment Service - Ticket generation with QR codes and PDF artifactsNotification Service - Transactional email delivery for order confirmationsIdentity Service - Authentication and user management with JWT tokens
Hexagonal Architecture (Ports & Adapters) Each microservice follows the hexagonal architecture pattern:
┌─────────────────────────────────────────┐ │ API Layer (HTTP) │ ← Presentation ├─────────────────────────────────────────┤ │ Application (Use Cases) │ ← MediatR handlers ├─────────────────────────────────────────┤ │ Domain (Business Logic) │ ← Pure business rules ├─────────────────────────────────────────┤ │ Infrastructure (Adapters) │ ← EF Core, Kafka, Redis └─────────────────────────────────────────┘
This separation ensures:
Testability - Domain logic has zero infrastructure dependenciesFlexibility - Swap databases or messaging systems without touching business logicMaintainability - Clear boundaries between layers
Event-Driven Communication The system uses Apache Kafka for asynchronous choreography of long-running processes:
Key Events:
reservation-created - Seat reserved with TTLreservation-expired - TTL elapsed, seat releasedpayment-succeeded / payment-failed - Payment outcometicket-issued - Ticket PDF generated and ready
CQRS Pattern Command and query responsibilities are separated:
Commands (writes) - Reserve seat, create order, process paymentQueries (reads) - Get event details, seat map, order status
This separation allows:
Optimized read models for fast queries
Complex write operations with business rules enforcement
Independent scaling of read and write workloads
Distributed Consistency Redis is used for distributed locking to prevent race conditions during seat reservations:// Pseudo-code using ( var lock = await _redisLock . AcquireAsync ( seatId , ttl : 30 )) { // Only one process can reserve this seat at a time var seat = await _repository . GetSeatAsync ( seatId ); if ( seat . Status == SeatStatus . Available ) { seat . Reserve ( customerId , expiresAt ); await _repository . SaveAsync ( seat ); } }
PostgreSQL provides ACID guarantees with optimistic locking (row versioning) for concurrent updates.Technology Stack Backend Services Component Technology Purpose Runtime .NET 9 Modern, high-performance framework API Minimal APIs Lightweight HTTP endpoints Mediator MediatR In-process messaging for CQRS ORM Entity Framework Core Database access and migrations Database PostgreSQL 17 Relational database with schema isolation Cache & Locks Redis 7 Distributed locking and TTL management Messaging Apache Kafka (Confluent) Event streaming and choreography Logging Serilog Structured logging Tracing OpenTelemetry Distributed tracing
Frontend Component Technology Framework Next.js 14 (App Router) Styling TailwindCSS Components Shadcn/UI Language TypeScript
Infrastructure Component Technology Containerization Docker & Docker Compose Orchestration Zookeeper (for Kafka) Schema Management EF Core Migrations
Architecture Overview The platform uses a hybrid communication model :
Database Schema Isolation A single PostgreSQL instance is shared across all services, but each bounded context owns its own schema:
Schema Service Tables bc_identityIdentity users, roles, tokens bc_catalogCatalog events, venues, seats (read model) bc_inventoryInventory reservations, seat_availability bc_orderingOrdering orders, order_items, carts bc_paymentPayment payments, transactions bc_fulfillmentFulfillment tickets, qr_codes bc_notificationNotification notifications, delivery_logs
This approach balances:
Operational simplicity - Single database to manageLogical isolation - Each service owns its dataCost efficiency - No need for multiple database instances in development
In production, you may want to split into separate database instances for true service independence and scalability.
Use Cases Primary Use Case: Event Ticket Purchase The core workflow enables customers to:
Browse Events - View available events with dates, venues, and pricingSelect Seats - Explore interactive seat maps showing real-time availabilityReserve Temporarily - Hold seats for 30 minutes with distributed lockingAdd to Cart - Build an order with multiple seatsComplete Payment - Process payment (simulated or real gateway)Receive Ticket - Get PDF ticket with QR code via email
Concurrency Handling The platform excels at handling concurrent access:
Scenario : 1,000 users try to reserve the same seat simultaneously// Only ONE reservation succeeds User A : POST / reservations → 200 OK ( seat reserved ) User B : POST / reservations → 409 Conflict ( seat already reserved ) User C : POST / reservations → 409 Conflict ( seat already reserved ) // ... 997 more conflicts
This is guaranteed through:
Redis distributed locks (cross-process coordination)PostgreSQL optimistic locking (row versioning)Idempotency keys (prevent duplicate operations)
Reservation Expiration Reservations automatically expire after 30 minutes:
T+0:00 → User reserves seat A1 T+0:01 → Seat status: RESERVED (expires at T+30:00) T+15:00 → User adds to cart (reservation extended) T+29:59 → User completes payment → Seat status: SOLD // Alternative flow: T+0:00 → User reserves seat A1 T+30:01 → Background job expires reservation T+30:02 → Seat status: AVAILABLE T+30:03 → kafka event: reservation-expired T+30:04 → Inventory releases seat
System Requirements Development Environment
Docker Desktop 4.0+ (with Docker Compose v2)Git 2.30+(Optional) .NET 9 SDK - Only if developing backend services locally(Optional) Node.js 20+ - Only if developing frontend locally
Minimum Hardware
RAM : 8 GB (16 GB recommended)CPU : 4 cores (8 cores recommended)Disk : 10 GB free space
macOS 12+ (Intel & Apple Silicon)
Windows 10/11 with WSL2
Linux (Ubuntu 20.04+, Debian 11+, Fedora 35+)
Getting Started Ready to run the platform? Continue to the Quickstart Guide for a 5-minute setup, or dive into the Installation Guide for detailed configuration options.
Quickstart Get the platform running in 5 minutes
Installation Detailed setup with troubleshooting
Project Documentation The source repository includes comprehensive documentation:
Document Description AI Workflow Prompt engineering and AI development process Human Checks Manual review and architectural decisions Technical Debt Known issues and improvement backlog TDD Report Test-driven development practices (ATDD) API Guide Frontend integration reference
Why SpecKit? SpecKit Ticketing Platform is designed to demonstrate:
Enterprise Patterns in Practice
Hexagonal Architecture - Clean separation of concernsCQRS - Command and query separationEvent Sourcing Lite - Domain events for process choreographySaga Pattern - Distributed transaction management
Real-World Challenges
Concurrency - Prevent double-booking with distributed locksConsistency - Maintain data integrity across servicesResilience - Handle partial failures gracefullyObservability - Trace requests across service boundaries
Modern Technology
.NET 9 - Latest framework featuresMinimal APIs - Lightweight, performant endpointsKafka - Industry-standard event streamingPostgreSQL - Robust relational database
Developer Experience
Zero configuration - Everything pre-configured in docker-composeFast startup - From clone to running in under 2 minutesClear documentation - Step-by-step guides and API referencesExtensible - Easy to add new features or swap implementations
Next Steps Explore the documentation:
Quickstart Installation API Reference Architecture Development Guide
New to microservices or event-driven architecture? Start with the Quickstart to see the system in action, then explore the architecture documentation to understand the design patterns. 