Files

m.jalmoudy ed5a490387 unkown commit

2025-12-02 19:39:58 +03:30

3.5 KiB

Raw Blame History

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

Clone the repository
Copy environment file:
```
cp .env.example .env
```
Install dependencies:
```
composer install
```
Start services:
```
docker-compose up -d
```

Initialize Cassandra schema:

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:

{
  "name": "FedEx",
  "email": "contact@fedex.com"
}

Success Response (201):

{
  "success": true,
  "data": {
    "message": "Carrier registered successfully",
    "carrier_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error Response (422):

{
  "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:

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

composer test

Development

For development mode, set in .env:

APP_ENV=development
APP_DEBUG=true
APP_LOG_LEVEL=debug

Production Deployment

Set production environment variables
Ensure proper Cassandra replication factor
Configure log rotation
Set up monitoring and alerting
Use a reverse proxy (nginx) for SSL termination
Enable PHP OPcache

License

MIT

3.5 KiB Raw Blame History