Skip to content

Open-source event management and ticket selling platform β€” perfect for concerts, conferences, and everything in between 🎟️ If you find this project helpful, please consider giving us a star ⭐️

10.5 KB
Raw Blame

Hi.Events Backend Architecture Overview

Introduction

Hi.Events is an open-source event management and ticketing platform built with Laravel. The backend implements a Domain-Driven Design (DDD) architecture with clear separation of concerns, enabling maintainable, testable, and scalable code.

High-Level Architecture

graph TB
    subgraph "HTTP Layer"
        A[Actions] --> B[Request Validation]
        A --> C[Authorization]
    end

    subgraph "Application Layer"
        D[Handlers] --> E[DTOs]
        D --> F[Transaction Management]
    end

    subgraph "Domain Layer"
        G[Domain Services] --> H[Domain Objects]
        G --> I[Domain Events]
    end

    subgraph "Infrastructure Layer"
        J[Repositories] --> K[Eloquent Models]
        L[External Services] --> M[Stripe/Email/etc]
        N[Event Listeners] --> O[Background Jobs]
    end

    A --> D
    D --> G
    G --> J
    G --> L
    D --> N

Architectural Layers

1. HTTP Layer (app/Http/)

Responsibility: Handle HTTP requests and responses

  • Actions (app/Http/Actions/) - Invokable controllers
  • Requests (app/Http/Request/) - Validation rules
  • Resources (app/Http/Resources/) - JSON API transformers
  • Middleware - Authentication, authorization, CORS

Key Pattern: All actions extend BaseAction which provides standardized response methods and authorization checks.

2. Application Layer (app/Services/Application/Handlers/)

Responsibility: Orchestrate domain services and manage use cases

  • Handlers - One per use case (e.g., CreateOrderHandler, UpdateEventHandler)
  • DTOs - Data Transfer Objects for passing data between layers
  • Transaction Management - Ensure data consistency
  • Event Dispatching - Trigger side effects

Key Pattern: Handlers receive DTOs from actions and orchestrate domain services.

3. Domain Layer (app/Services/Domain/)

Responsibility: Core business logic

  • Domain Services - Business logic implementation
  • Domain Objects (app/DomainObjects/) - Type-safe data representations
  • Enums (app/DomainObjects/Enums/, app/DomainObjects/Status/) - Domain constants
  • Validators - Business rule validation

Key Pattern: Services are highly focused (single responsibility) and compose to handle complex operations.

4. Infrastructure Layer

Responsibility: External concerns and technical implementations

  • Repositories (app/Repository/) - Data access abstraction
  • External Services (app/Services/Infrastructure/) - Stripe, email, etc.
  • Event Listeners (app/Listeners/) - React to domain events
  • Background Jobs (app/Jobs/) - Asynchronous processing
  • Database - Eloquent models and migrations

Key Pattern: Infrastructure depends on domain interfaces, not vice versa.

Core Components

Domain Objects

Auto-generated immutable representations of database entities.

  • Generated via php artisan generate-domain-objects
  • Abstract classes in app/DomainObjects/Generated/ (read-only)
  • Concrete classes in app/DomainObjects/ (customizable)
  • Provide type-safe getters/setters and constants for field names

DTOs (Data Transfer Objects)

Immutable data containers for passing data between layers.

  • Modern: Extend BaseDataObject (using Spatie Laravel Data)
  • Legacy: Extend BaseDTO (being phased out)
  • Use constructor property promotion with readonly properties
  • Type-safe with enums and primitives

Repositories

Interface-based data access layer.

  • 40+ base methods for CRUD operations
  • Return domain objects, never Eloquent models
  • Support eager loading, pagination, filtering
  • Registered in RepositoryServiceProvider

Events & Jobs

Dual event system for internal workflows and external integrations.

  • Application Events (app/Events/) - Internal domain logic
  • Infrastructure Events (app/Services/Infrastructure/DomainEvents/) - Webhooks
  • Listeners (app/Listeners/) - React to events, dispatch jobs
  • Jobs (app/Jobs/) - Asynchronous processing with retry logic

Request Flow

sequenceDiagram
    participant Client
    participant Action
    participant Handler
    participant Service
    participant Repository
    participant Database

    Client->>Action: HTTP Request
    Action->>Action: Validate Request
    Action->>Action: Check Authorization
    Action->>Handler: Pass DTO
    Handler->>Service: Call Domain Service
    Service->>Repository: Query/Persist Data
    Repository->>Database: Execute Query
    Database-->>Repository: Return Model
    Repository-->>Service: Return Domain Object
    Service-->>Handler: Return Domain Object
    Handler-->>Action: Return Domain Object
    Action->>Action: Transform to Resource
    Action-->>Client: JSON Response

Key Design Patterns

1. Dependency Injection

All services, repositories, and handlers use constructor injection for dependencies.

class CreateOrderHandler
{
    public function __construct(
        private readonly OrderRepositoryInterface $orderRepository,
        private readonly OrderManagementService $orderManagementService,
        private readonly DatabaseManager $databaseManager,
    ) {}
}

2. Repository Pattern

All data access goes through repository interfaces.

interface OrderRepositoryInterface extends RepositoryInterface
{
    public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator;
}

3. DTO Pattern

Data passed between layers using immutable DTOs.

class CreateOrderDTO extends BaseDataObject
{
    public function __construct(
        public readonly int $eventId,
        public readonly Collection $products,
        public readonly ?string $promoCode = null,
    ) {}
}

4. Service Layer Pattern

Business logic encapsulated in focused service classes.

class MarkOrderAsPaidService
{
    public function markOrderAsPaid(int $orderId, int $eventId): OrderDomainObject
    {
        return DB::transaction(function() {
            // Business logic
        });
    }
}

5. Event-Driven Architecture

Domain events enable decoupled communication.

OrderStatusChangedEvent::dispatch($order);
// Triggers: email sending, statistics updates, webhook delivery

Multi-Tenancy Architecture

Hi.Events implements account-based multi-tenancy:

Account (Tenant)
β”œβ”€β”€ Users (many-to-many with roles)
β”œβ”€β”€ Organizers
β”‚   └── Events
β”‚       β”œβ”€β”€ Products/Tickets
β”‚       β”œβ”€β”€ Orders
β”‚       β”œβ”€β”€ Attendees
β”‚       └── Settings
  • Each account is an independent tenant
  • Data isolation through account_id foreign keys
  • User context: User::getCurrentAccountId()

Technology Stack

  • Framework: Laravel 11
  • Database: PostgreSQL with JSONB support
  • Authentication: JWT (Laravel Passport/Sanctum)
  • Queue: Laravel Queues (Redis/Database)
  • Cache: Redis
  • Payment: Stripe with Stripe Connect
  • Email: Laravel Mail

Best Practices

1. Always Use DTOs

Pass data to handlers using DTOs, not arrays or individual parameters.

βœ… Good:

$handler->handle(new CreateOrderDTO(...));

❌ Bad:

$handler->handle($eventId, $products, $promoCode);

2. Use Domain Object Constants

Reference fields using constants, not strings.

βœ… Good:

$repository->findWhere([OrderDomainObjectAbstract::STATUS => 'COMPLETED']);

❌ Bad:

$repository->findWhere(['status' => 'COMPLETED']);

3. Favor Base Repository Methods

Use existing repository methods before creating custom ones.

βœ… Good:

$repository->findFirstWhere(['event_id' => $eventId]);

❌ Bad:

$repository->findByEventId($eventId); // Custom method for common pattern

4. Extend BaseAction for HTTP

All HTTP actions should extend BaseAction and use its response methods.

βœ… Good:

return $this->resourceResponse(OrderResource::class, $order, ResponseCodes::HTTP_CREATED);

❌ Bad:

return response()->json(['data' => $order], 201);

5. Use Enums for Constants

Define domain constants as enums, not arrays or class constants.

βœ… Good:

enum OrderStatus { case COMPLETED; case CANCELLED; }

❌ Bad:

class OrderStatus { const COMPLETED = 'completed'; }

File Organization

backend/app/
β”œβ”€β”€ Console/              # Artisan commands
β”œβ”€β”€ DomainObjects/        # Auto-generated domain objects
β”‚   β”œβ”€β”€ Generated/        # Don't edit
β”‚   β”œβ”€β”€ Enums/           # General enums
β”‚   └── Status/          # Status enums
β”œβ”€β”€ Events/              # Application events
β”œβ”€β”€ Exceptions/          # Custom exceptions
β”œβ”€β”€ Http/
β”‚   β”œβ”€β”€ Actions/         # Invokable controllers
β”‚   β”œβ”€β”€ Request/         # Form requests
β”‚   └── Resources/       # JSON API resources
β”œβ”€β”€ Jobs/                # Background jobs
β”œβ”€β”€ Listeners/           # Event listeners
β”œβ”€β”€ Models/              # Eloquent models
β”œβ”€β”€ Repository/
β”‚   β”œβ”€β”€ Interfaces/      # Repository contracts
β”‚   └── Eloquent/        # Implementations
β”œβ”€β”€ Services/
β”‚   β”œβ”€β”€ Application/     # Application handlers
β”‚   β”‚   └── Handlers/    # Use case handlers
β”‚   β”œβ”€β”€ Domain/          # Domain services
β”‚   └── Infrastructure/  # External services
└── Validators/          # Validation rules

Testing Strategy

  • Unit Tests (tests/Unit/) - Test handlers and services in isolation
  • Use DatabaseTransactions trait, not RefreshDatabase
  • Mock repositories using Mockery
  • Test both success and failure paths
  • Run: php artisan test --testsuite=Unit

Performance Considerations

  • Eager Loading: Use loadRelation() to avoid N+1 queries
  • Indexes: All foreign keys and frequently queried fields are indexed
  • JSONB: Use PostgreSQL JSONB for flexible schema
  • Queue: Offload heavy operations to background jobs
  • Caching: Cache expensive queries and computed data

Security

  • Authorization: Entity-level checks via isActionAuthorized()
  • Authentication: JWT tokens with account context
  • Validation: All inputs validated via FormRequests
  • SQL Injection: Protected by Eloquent ORM
  • CSRF: API uses token-based auth (no CSRF)

Related Documentation