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 βοΈ
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_idforeign 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
DatabaseTransactionstrait, notRefreshDatabase - 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)