unkown commit

README.md

@@ -1,3 +1,165 @@
-# Distributing Carriers
+# Distributing Carriers Application
 
-Distributing Carriers Application.
+A production-ready event-sourced application built with DDD, CQRS, and Event Sourcing patterns using PHP 8+ and Apache Cassandra.
+
+## Features
+
+- **Domain-Driven Design (DDD)**: Clean separation of domain, application, and infrastructure layers
+- **Event Sourcing**: All state changes captured as immutable events in Cassandra
+- **CQRS**: Command-Query Responsibility Segregation with command bus
+- **Production-Ready**: Comprehensive error handling, logging, validation, and monitoring
+- **Optimistic Concurrency Control**: Version-based conflict detection
+- **Retry Logic**: Automatic retry with exponential backoff for transient failures
+- **Structured Logging**: JSON-formatted logs with Monolog
+- **Input Validation**: Multi-layer validation with detailed error messages
+- **Type Safety**: Strict types and value objects for domain integrity
+
+## Requirements
+
+- PHP 8.0 or higher
+- Cassandra PHP extension
+- Docker & Docker Compose
+- Composer
+
+## Installation
+
+1. Clone the repository
+2. Copy environment file:
+   ```bash
+   cp .env.example .env
+   ```
+
+3. Install dependencies:
+   ```bash
+   composer install
+   ```
+
+4. Start services:
+   ```bash
+   docker-compose up -d
+   ```
+
+5. Initialize Cassandra schema:
+   ```bash
+   docker exec -it cassandra cqlsh -e "
+   CREATE KEYSPACE IF NOT EXISTS event_store 
+   WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};
+
+   USE event_store;
+
+   CREATE TABLE IF NOT EXISTS events (
+       aggregate_id text,
+       version int,
+       event_type text,
+       payload text,
+       created_at timestamp,
+       PRIMARY KEY (aggregate_id, version)
+   ) WITH CLUSTERING ORDER BY (version ASC);
+   "
+   ```
+
+## API Endpoints
+
+### Register Carrier
+
+**POST** `/register-carrier`
+
+Request:
+```json
+{
+  "name": "FedEx",
+  "email": "contact@fedex.com"
+}
+```
+
+Success Response (201):
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Carrier registered successfully",
+    "carrier_id": "550e8400-e29b-41d4-a716-446655440000"
+  }
+}
+```
+
+Error Response (422):
+```json
+{
+  "success": false,
+  "error": {
+    "message": "Validation failed",
+    "code": 422,
+    "details": {
+      "email": "The email must be a valid email address"
+    }
+  }
+}
+```
+
+## Architecture
+
+### Layers
+
+- **Domain**: Core business logic, aggregates, events, value objects
+- **Application**: Use cases, command handlers, DTOs
+- **Infrastructure**: Technical implementations (Cassandra, logging, routing)
+
+### Key Components
+
+- **AggregateRoot**: Base class for domain aggregates with event sourcing
+- **CommandBus**: Routes commands to appropriate handlers
+- **EventStore**: Persists and retrieves domain events from Cassandra
+- **Logger**: Structured logging with rotation and JSON formatting
+- **Validator**: Input validation with detailed error messages
+
+## Configuration
+
+Edit `.env` file:
+
+```env
+APP_ENV=production
+APP_DEBUG=false
+APP_LOG_LEVEL=info
+
+CASSANDRA_HOST=cassandra
+CASSANDRA_PORT=9042
+CASSANDRA_KEYSPACE=event_store
+
+MAX_REQUEST_SIZE=1048576
+REQUEST_TIMEOUT=30
+```
+
+## Logging
+
+Logs are written to `logs/app.log` in JSON format with automatic rotation (30 days).
+
+Log levels: debug, info, warning, error, critical
+
+## Testing
+
+```bash
+composer test
+```
+
+## Development
+
+For development mode, set in `.env`:
+```env
+APP_ENV=development
+APP_DEBUG=true
+APP_LOG_LEVEL=debug
+```
+
+## Production Deployment
+
+1. Set production environment variables
+2. Ensure proper Cassandra replication factor
+3. Configure log rotation
+4. Set up monitoring and alerting
+5. Use a reverse proxy (nginx) for SSL termination
+6. Enable PHP OPcache
+
+## License
+
+MIT