# 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