Welcome to the Flash Sale Microservice documentation - a high-performance, production-grade Go service designed to handle massive traffic spikes during hourly flash sales.

This microservice implements a robust flash sale system that can handle 10,000 items per hour with high concurrency and strict consistency guarantees. Built with Go's standard library and following Domain-Driven Design principles, it's optimized for maximum throughput while preventing overselling.

• High Throughput: Designed to handle thousands of concurrent requests
• Atomic Operations: Prevents overselling with strict consistency guarantees
• No Reservations: Items are only reserved during the actual purchase moment
• Analytics Ready: All checkout attempts are logged for business intelligence
• Zero Dependencies: Built with Go standard library only (minimal external deps)
• Production Ready: Comprehensive monitoring, logging, and error handling

The service follows Domain-Driven Design (DDD) principles with clean separation of concerns:

├── domain/          # Pure business logic (no external dependencies)
├── application/     # Use cases and application services
├── infrastructure/  # External concerns (DB, HTTP, Redis, etc.)
└── pkg/            # Shared utilities and helpers

• Go 1.24+
• Docker & Docker Compose
• PostgreSQL 15+
• Redis 7+

bash
# Clone the repository
git clone <repository-url>
cd flash-sale-service

# Start with Docker Compose
docker-compose up -d

# Or build and run manually
make build
./flashsale

The service will be available at http://localhost:8080

• Target RPS: 10,000+ requests per second
• Sale Duration: 1 hour per sale
• Items Per Sale: 10,000 unique items
• User Limit: 10 items per user per sale
• Response Time: Sub-100ms for checkout, sub-200ms for purchase

Method | Endpoint | Description
-- | -- | --
POST | /checkout?user_id={id}&id={id} | Add item to user's checkout
POST | /purchase?code={checkout_code} | Execute purchase with checkout code
GET | /sales/active | Get current active sale
GET | /sales/{id}/items | List items for a specific sale

• Duration: Each sale lasts exactly 1 hour
• Items: 10,000 unique items generated per sale
• Global Limit: Maximum 10,000 items can be sold per sale
• User Limit: Each user can purchase maximum 10 items per sale

1. User adds items to checkout (no reservation)
2. System generates/reuses unique checkout code
3. User can add up to 10 items before purchasing
4. All checkout attempts are logged for analytics

1. User submits checkout code for purchase
2. System atomically attempts to purchase all items
3. Already-sold items are reported in response
4. Successful purchases are immediately committed

• Language: Go 1.21+ (standard library only)
• Database: PostgreSQL 15+ with connection pooling
• Cache: Redis 7+ for distributed state and atomic operations
• Deployment: Docker with multi-stage builds

• No Web Frameworks: Pure net/http for maximum performance
• No ORM: Direct SQL with database/sql and pgx driver
• Minimal Dependencies: Only essential libraries (postgres driver, redis client, prometheus)
• Bloom Filters: Fast rejection of already-sold items
• Lua Scripts: Atomic Redis operations for consistency

• Request latency histograms (P50, P95, P99)
• Throughput counters (requests/second)
• Error rates by type and endpoint
• Business metrics (items sold, checkout attempts)
• Database and Redis performance metrics

• /health - Service liveness and dependency status
• /metrics - Prometheus metrics endpoint
• Database connection monitoring
• Redis connectivity and performance

• Structured JSON logging with correlation IDs
• Request/response logging with performance metrics
• Error tracking with full context
• Business event logging for analytics

bash
# Light load test
make load-test-light

# Heavy load test  
make load-test-heavy

# Stress test
make load-test-stress

# Realistic user behavior simulation
make realistic-test