feat: add project documentation

README.md

@@ -42,34 +42,128 @@ Your task is to extract the high-throughput ticket purchasing component and exte
 
 ### Prerequisites
 
-- Node.js (v14+ recommended)
-- npm
-- Redis (installed locally or via Docker, as per the provided docker-compose configuration)
+- Node.js (v18+ recommended)
+- npm or yarn
+- Docker and Docker Compose
+- Git
 
-### Setup
+### Quick Start
 
-1. Clone the repository.
-2. Install dependencies:
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd module4_backend_project
+   ```
+
+2. **Install dependencies**
+   ```bash
    npm install
-3. (Optional) Copy the environment variable template:
+   ```
+
+3. **Set up environment**
+   ```bash
    cp .env.example .env
-4. Seed the Redis store with tickets for multiple events. You might modify the seeding script to handle multiple event keys (e.g., `event:1:tickets`, `event:2:tickets`, etc.).
-5. Start the application:
-   npm start
+   # Edit .env file if needed
+   ```
+
+4. **Start with Docker (Recommended)**
+   ```bash
+   # Start core services (Redis + App)
+   docker-compose up -d
+   
+   # Or start with monitoring (Prometheus + Grafana)
+   docker-compose --profile monitoring up -d
+   ```
+
+5. **Seed the database**
+   ```bash
+   # Seed 5 events with 10,000 tickets each
+   npm run seed
+   
+   # Custom seeding: 3 events with 5,000 tickets each
+   npm run seed 3 5000
+   ```
+
+### Manual Setup (Development)
+
+If you prefer to run components separately:
+
+1. **Start Redis**
+   ```bash
+   docker-compose up -d redis
+   ```
+
+2. **Start the application**
+   ```bash
+   npm run dev  # Development with auto-reload
+   # or
+   npm start    # Production mode
+   ```
+
+### API Endpoints
+
+Once running, the following endpoints are available:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/health` | System health check |
+| GET | `/events` | List all events with statistics |
+| GET | `/events/:eventId` | Get specific event details |
+| POST | `/buy/:eventId` | Purchase a ticket for an event |
+| GET | `/tickets/:purchaseId` | Download ticket PDF |
+| GET | `/metrics` | Real-time system metrics |
+| GET | `/admin/pdf-stats` | PDF management statistics |
+| POST | `/admin/cleanup-tickets` | Cleanup old ticket files |
 
 ### Load Testing
 
-Simulate high load using a tool like [autocannon](https://github.com/mcollina/autocannon) or [wrk](https://github.com/wg/wrk). For example, to simulate 5000 concurrent connections on event 1:
+The system includes a comprehensive load testing framework:
 
-npx autocannon -c 5000 -d 30 http://localhost:3049/buy/1
+```bash
+# Run full test suite (5000+ concurrent connections)
+npm run test:load -- --full
 
-### Metrics
+# Test specific event
+npm run test:load -- --event 1 --connections 5000 --duration 30
 
-Access real-time service metrics at:
+# Multi-event concurrent testing
+npm run test:load -- --multi --events 1,2,3 --connections 6000
 
-http://localhost:3049/metrics
+# Custom load test
+node tests/load-test.js --event 2 --connections 1000 --duration 10
+```
 
-These metrics should include data on tickets sold, remaining tickets per event, and any instances where the fallback mechanism was activated.
+### Monitoring & Metrics
+
+#### Application Metrics
+Access real-time service metrics at: http://localhost:3049/metrics
+
+#### Prometheus (if enabled)
+Prometheus dashboard: http://localhost:9090
+
+#### Grafana (if enabled)
+Grafana dashboard: http://localhost:3000
+- Username: `admin`
+- Password: `admin`
+
+### Docker Commands
+
+```bash
+# Start core services
+docker-compose up -d
+
+# Start with monitoring
+docker-compose --profile monitoring up -d
+
+# View logs
+docker-compose logs -f app
+
+# Stop services
+docker-compose down
+
+# Rebuild and restart
+docker-compose up -d --build
+```
 
 ## Evaluation Criteria