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 βοΈ
PHP attendize-alternativedoor-managementevent-check-inevent-managementevent-registrationevent-ticketingeventbrite-alternativeeventslaravelopen-sourcephpreactself-hostedsell-ticketssell-tickets-onlineticket-sellingticketing-systemtickettailor-alternativetito-alternative
Feature: Add BE docs (#864)
Dave Earley7bb330742d25
diff --git a/backend/docs/README.md b/backend/docs/README.mdnew file mode 100644index 000000000..2b98dfddb--- /dev/null+++ b/backend/docs/README.md@@ -0,0 +1,245 @@+# Hi.Events Backend Documentation++Welcome to the Hi.Events backend documentation. This directory contains comprehensive guides on the architecture, patterns, and best practices used throughout the backend codebase.++**π¨ These docs are AI generated and are not 100% accurate. Always verify anything important by looking at the actual code.**++## Documentation Index++### [Architecture Overview](architecture-overview.md)+**Start here** - High-level overview of the entire backend architecture.++**Contents**:+- Architectural layers (HTTP, Application, Domain, Infrastructure)+- Core components (Domain Objects, DTOs, Repositories, Events)+- Request flow and data flow+- Key design patterns+- Multi-tenancy architecture+- Best practices summary++**Who should read**: Everyone working on the backend++---++### [Domain-Driven Design](domain-driven-design.md)+Deep dive into the DDD patterns used in Hi.Events.++**Contents**:+- Application Layer (Handlers)+- Domain Services Layer+- Data Transfer Objects (DTOs)+- Domain Objects (auto-generated)+- Enums and constants+- DTO flow patterns+- Transaction management+- Service composition+- Validation patterns++**Who should read**: Backend developers implementing new features++---++### [Database Schema](database-schema.md)+Complete database schema architecture and entity relationships.++**Contents**:+- Core entity hierarchy+- Multi-tenancy architecture+- All database entities (Account, Event, Order, Attendee, etc.)+- Entity relationships and diagrams+- Architectural patterns (soft deletes, JSONB, indexes)+- PostgreSQL-specific features++**Who should read**: Backend developers, database administrators++---++### [Repository Pattern](repository-pattern.md)+Guide to the repository pattern implementation.++**Contents**:+- Base repository interface (40+ methods)+- Creating new repositories+- Usage in handlers+- Best practices (favor base methods, eager loading)+- Common patterns (pagination, filters, bulk operations)+- Testing with mocks++**Who should read**: Backend developers working with data access++---++### [Events and Background Jobs](events-and-jobs.md)+Event-driven architecture and asynchronous processing.++**Contents**:+- Application Events vs Infrastructure Events+- Event listeners+- Background jobs+- Event flow examples+- Retry strategies+- Transaction boundaries+- Queue separation++**Who should read**: Backend developers implementing workflows and integrations++---++### [API Patterns and HTTP Layer](api-patterns.md)+HTTP layer patterns and API design.++**Contents**:+- BaseAction pattern+- Response methods+- Authorization patterns+- JSON API resources+- Routing patterns+- Request validation+- Exception handling++**Who should read**: Backend developers building API endpoints++---++## Quick Reference++### Common Tasks++#### Creating a New Feature++1. **Read**: [Architecture Overview](architecture-overview.md) - Understand the layers+2. **Read**: [Domain-Driven Design](domain-driven-design.md) - Understand DTOs, Handlers, Services+3. **Reference**: Existing feature in `/prompts` directory+4. **Implement**: Following the established patterns++#### Adding a New Entity++1. **Create migration**: `php artisan make:migration create_xxx_table`+2. **Run migration**: `php artisan migrate`+3. **Generate domain objects**: `php artisan generate-domain-objects`+4. **Create repository interface and implementation**: See [Repository Pattern](repository-pattern.md)+5. **Register repository**: Add to `RepositoryServiceProvider`+6. **Update database docs**: Reference [Database Schema](database-schema.md)++#### Adding a New API Endpoint++1. **Create FormRequest**: See [API Patterns](api-patterns.md#request-validation)+2. **Create Action**: Extend `BaseAction`, see [API Patterns](api-patterns.md#baseaction-pattern)+3. **Create DTO**: Extend `BaseDataObject`, see [DDD](domain-driven-design.md#dtos)+4. **Create Handler**: See [DDD](domain-driven-design.md#application-layer)+5. **Create Domain Service** (if needed): See [DDD](domain-driven-design.md#domain-services-layer)+6. **Create JSON Resource**: See [API Patterns](api-patterns.md#json-api-resources)+7. **Add route**: `routes/api.php`++#### Adding Background Processing++1. **Create Event**: See [Events and Jobs](events-and-jobs.md#application-events)+2. **Create Job**: See [Events and Jobs](events-and-jobs.md#background-jobs)+3. **Create Listener**: See [Events and Jobs](events-and-jobs.md#event-listeners)+4. **Register** (if needed): See [Events and Jobs](events-and-jobs.md#event-registration)++### Key Commands++```bash+# Backend (run in Docker container)+cd docker/development+docker compose -f docker-compose.dev.yml exec backend bash++# Generate domain objects+php artisan generate-domain-objects++# Run migrations+php artisan migrate++# Run unit tests+php artisan test --testsuite=Unit++# Run specific test+php artisan test --filter=TestName+```++### File Locations++```+backend/+βββ app/+β βββ DomainObjects/ # Auto-generated domain objects+β β βββ Generated/ # Don't edit these+β β βββ Enums/ # General enums+β β βββ Status/ # Status enums+β βββ Events/ # Application events+β βββ Http/+β β βββ Actions/ # HTTP actions (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+βββ database/+β βββ migrations/ # Database migrations+βββ routes/+ βββ api.php # API routes+```++## Architecture Principles++### Core Principles++1. **Domain-Driven Design**: Clear separation between domain, application, and infrastructure+2. **Repository Pattern**: All data access through interfaces+3. **DTO Pattern**: Immutable data transfer between layers+4. **Event-Driven**: Decoupled communication via events+5. **Type Safety**: Strong typing with domain objects and DTOs++### Best Practices++1. **Always extend `BaseDataObject`** for new DTOs (not `BaseDTO`)+2. **Use domain object constants** for field names+3. **Favor base repository methods** over custom methods+4. **Extend `BaseAction`** for all HTTP actions+5. **Use enums** for domain constants++### Code Quality++- Follow PSR-12 coding standards+- Wrap all translatable strings in `__()` helper+- Create unit tests for new features+- Don't add comments unless absolutely necessary+- Refactor complex code instead of documenting it++## External Resources++- [CLAUDE.md](../../CLAUDE.md) - Project guidelines for AI assistants+- [Laravel Documentation](https://laravel.com/docs)+- [Spatie Laravel Data](https://spatie.be/docs/laravel-data)+- [PostgreSQL Documentation](https://www.postgresql.org/docs/)++## Contributing++When adding new features or making significant changes:++1. Follow the patterns documented here+2. Update relevant documentation if patterns change+3. Add examples to `/prompts` for reference+4. Ensure tests pass: `php artisan test --testsuite=Unit`++## Getting Help++1. **Start with**: [Architecture Overview](architecture-overview.md)+2. **Look at examples**: `/prompts` directory contains feature documentation+3. **Check CLAUDE.md**: Project-specific guidelines and patterns+4. **Reference specific guides**: Use the documentation index above++---++**Last Updated**: 2025-10-29++**Documentation Version**: 1.0diff --git a/backend/docs/api-patterns.md b/backend/docs/api-patterns.mdnew file mode 100644index 000000000..af4664889--- /dev/null+++ b/backend/docs/api-patterns.md@@ -0,0 +1,853 @@+# API Patterns and HTTP Layer++## Overview++The Hi.Events backend HTTP layer uses a standardized pattern built around invokable action classes that extend `BaseAction`. This provides consistent response methods, authorization patterns, and request handling across the entire API.++```mermaid+graph TB+ A[HTTP Request] --> B[Middleware]+ B --> C[Request Validation]+ C --> D[Action]+ D --> E[Authorization Check]+ E --> F[Handler]+ F --> G[Domain Service]+ G --> H[Repository]+ H --> F+ F --> D+ D --> I[JSON Resource]+ I --> J[HTTP Response]+```++## BaseAction Pattern++### Core Concept++All HTTP actions extend `BaseAction` which provides standardized methods for:+- Handling responses (JSON, resources, errors)+- Authorization checks+- Authentication+- Request parameter parsing++**File**: `backend/app/Http/Actions/BaseAction.php`++### Action Structure++```php+namespace HiEvents\Http\Actions\PromoCodes;++use HiEvents\Http\Actions\BaseAction;++class CreatePromoCodeAction extends BaseAction+{+ private CreatePromoCodeHandler $handler;++ public function __construct(CreatePromoCodeHandler $handler)+ {+ $this->handler = $handler;+ }++ public function __invoke(CreatePromoCodeRequest $request, int $eventId): JsonResponse+ {+ // 1. Authorization check+ $this->isActionAuthorized($eventId, EventDomainObject::class);++ // 2. Build DTO from validated request+ try {+ $promoCode = $this->handler->handle($eventId, new UpsertPromoCodeDTO(+ code: strtolower($request->input('code')),+ event_id: $eventId,+ discount_type: PromoCodeDiscountTypeEnum::fromName($request->input('discount_type')),+ discount: $request->float('discount'),+ // ...+ ));+ } catch (ResourceConflictException $e) {+ throw ValidationException::withMessages([+ 'code' => $e->getMessage(),+ ]);+ }++ // 3. Return resource response+ return $this->resourceResponse(+ PromoCodeResource::class,+ $promoCode,+ ResponseCodes::HTTP_CREATED+ );+ }+}+```++**File**: `backend/app/Http/Actions/PromoCodes/CreatePromoCodeAction.php`++### Key Principles++1. **Single Invokable Method**: Use `__invoke()` magic method+2. **Dependency Injection**: Handler services injected via constructor+3. **Thin Controllers**: Minimal logic - delegate to handlers+4. **Exception Handling**: Convert domain exceptions to ValidationException+5. **Type Safety**: Use DTOs for passing data to handlers++## Response Methods++### resourceResponse()++Transform domain objects/collections into JSON API resources.++```php+protected function resourceResponse(+ string $resource,+ Collection|DomainObjectInterface|LengthAwarePaginator|BaseDTO $data,+ int $statusCode = ResponseCodes::HTTP_OK,+ array $meta = [],+ array $headers = [],+ array $errors = [],+): JsonResponse+```++**Usage**:+```php+return $this->resourceResponse(+ PromoCodeResource::class,+ $promoCode,+ ResponseCodes::HTTP_CREATED+);+```++**Response Format**:+```json+{+ "data": {+ "id": 123,+ "code": "SUMMER2025",+ "discount": 20.00,+ "discount_type": "PERCENTAGE"+ }+}+```++### filterableResourceResponse()++Special response for filterable/sortable resources with metadata.++```php+protected function filterableResourceResponse(+ string $resource,+ Collection|DomainObjectInterface|LengthAwarePaginator $data,+ string $domainObject,+ int $statusCode = ResponseCodes::HTTP_OK,+): JsonResponse+```++**Usage**:+```php+return $this->filterableResourceResponse(+ resource: OrderResource::class,+ data: $orders,+ domainObject: OrderDomainObject::class+);+```++**Response Format**:+```json+{+ "data": [...],+ "meta": {+ "allowed_sorts": ["created_at", "total_gross", "status"],+ "allowed_filters": ["status", "payment_status", "event_id"],+ "pagination": {+ "total": 150,+ "per_page": 20,+ "current_page": 1+ }+ }+}+```++### jsonResponse()++Return raw JSON data (not wrapped in a resource).++```php+protected function jsonResponse(+ mixed $data,+ int $statusCode = ResponseCodes::HTTP_OK,+ bool $wrapInData = false,+): JsonResponse+```++### errorResponse()++Return error response with message.++```php+protected function errorResponse(+ string $message,+ int $statusCode = ResponseCodes::HTTP_BAD_REQUEST,+ array $errors = [],+): JsonResponse+```++**Usage**:+```php+catch (UnauthorizedException $e) {+ return $this->errorResponse(+ message: $e->getMessage(),+ statusCode: ResponseCodes::HTTP_UNAUTHORIZED,+ );+}+```++**Response Format**:+```json+{+ "message": "Unauthorized access",+ "errors": {}+}+```++### deletedResponse()++Return 204 No Content for successful deletions.++```php+protected function deletedResponse(): LaravelResponse+```++**Usage**:+```php+$this->handler->handle($productId, $eventId);+return $this->deletedResponse();+```++### Other Response Methods++```php+protected function notFoundResponse(): LaravelResponse; // 404+protected function noContentResponse(int $status = 204): LaravelResponse; // 204+```++## Authorization Patterns++### isActionAuthorized()++Primary authorization method used throughout the codebase.++```php+protected function isActionAuthorized(+ int $entityId,+ string $entityType,+ Role $minimumRole = Role::ORGANIZER+): void+```++**Usage**:+```php+public function __invoke(int $eventId, Request $request): JsonResponse+{+ // Check if user has access to this event+ $this->isActionAuthorized($eventId, EventDomainObject::class);++ // Continue with action logic...+}+```++### How Authorization Works++The `IsAuthorizedService` performs these checks:++1. **User Status Validation**: Ensures user is ACTIVE+2. **Role Validation**: Checks minimum role requirement+3. **Entity Ownership Validation**: Verifies entity belongs to authenticated account++**Implementation**:+```php+public function isActionAuthorized(+ int $entityId,+ string $entityType,+ UserDomainObject $authUser,+ int $authAccountId,+ Role $minimumRole+): void {+ $this->validateUserStatus($authUser);+ $this->validateUserRole($minimumRole, $authUser);++ // Fetch entity and verify ownership+ $repository = $this->getRepositoryForEntity($entityType);+ $entity = $repository->findById($entityId);++ if ($entity->getAccountId() !== $authAccountId) {+ throw new UnauthorizedException();+ }+}+```++### Alternative Authorization Methods++```php+// For actions that don't need entity-level authorization+protected function minimumAllowedRole(Role $minimumRole): void;++// Get current authenticated user+protected function getAuthenticatedUser(): UserDomainObject;++// Get current authenticated account ID+protected function getAuthenticatedAccountId(): int;++// Check if user is authenticated (boolean)+protected function isUserAuthenticated(): bool;+```++### Public Actions++Public actions don't call `isActionAuthorized()` but may have custom logic:++```php+public function __invoke(int $eventId, Request $request): JsonResponse+{+ $event = $this->handler->handle(GetPublicEventDTO::fromArray([+ 'eventId' => $eventId,+ 'isAuthenticated' => $this->isUserAuthenticated(),+ ]));++ // Custom authorization+ if (!$this->canUserViewEvent($event)) {+ return $this->notFoundResponse();+ }++ return $this->resourceResponse(EventResourcePublic::class, $event);+}++private function canUserViewEvent(EventDomainObject $event): bool+{+ // Public events are viewable by anyone+ if ($event->getStatus() === EventStatus::LIVE->name) {+ return true;+ }++ // Draft events only viewable by account members+ if ($this->isUserAuthenticated()+ && $event->getAccountId() === $this->getAuthenticatedAccountId()) {+ return true;+ }++ return false;+}+```++## JSON API Resources++### BaseResource++All resources extend `BaseResource`:++**File**: `backend/app/Resources/BaseResource.php`++```php+abstract class BaseResource extends JsonResource+{+ protected static array $additionalData = [];++ public static function collectionWithAdditionalData($resource, $data): JsonResource+ {+ static::$additionalData = $data;+ return static::collection($resource);+ }++ public function getAdditionalDataByKey(string $key)+ {+ return static::$additionalData[$key] ?? null;+ }+}+```++### Simple Resource++**File**: `backend/app/Resources/PromoCode/PromoCodeResource.php`++```php+/**+ * @mixin PromoCodeDomainObject+ */+class PromoCodeResource extends JsonResource+{+ public function toArray(Request $request): array+ {+ return [+ 'id' => $this->getId(),+ 'code' => $this->getCode(),+ 'applicable_product_ids' => $this->getApplicableProductIds(),+ 'discount' => $this->getDiscount(),+ 'discount_type' => $this->getDiscountType(),+ 'created_at' => $this->getCreatedAt(),+ 'updated_at' => $this->getUpdatedAt(),+ 'expiry_date' => $this->getExpiryDate(),+ 'max_allowed_usages' => $this->getMaxAllowedUsages(),+ ];+ }+}+```++### Resource with Nested Resources++**File**: `backend/app/Resources/Order/OrderResource.php`++```php+/**+ * @mixin OrderDomainObject+ */+class OrderResource extends BaseResource+{+ public function toArray(Request $request): array+ {+ return [+ 'id' => $this->getId(),+ 'short_id' => $this->getShortId(),+ 'total_gross' => $this->getTotalGross(),+ 'status' => $this->getStatus(),++ // Conditional nested resources+ 'order_items' => $this->when(+ !is_null($this->getOrderItems()),+ fn() => OrderItemResource::collection($this->getOrderItems())+ ),+ 'attendees' => $this->when(+ !is_null($this->getAttendees()),+ fn() => AttendeeResource::collection($this->getAttendees())+ ),+ 'latest_invoice' => $this->when(+ !is_null($this->getLatestInvoice()),+ fn() => (new InvoiceResource($this->getLatestInvoice()))->toArray($request),+ ),+ ];+ }+}+```++### Resource Patterns++1. **@mixin Annotation**: Provides IDE autocomplete+```php+/**+ * @mixin EventDomainObject+ */+```++2. **Use Getter Methods**: Always use domain object methods+```php+'id' => $this->getId(),+'title' => $this->getTitle(),+```++3. **Conditional Fields**: Use `$this->when()` for optional fields+```php+'settings' => $this->when(+ !is_null($this->getSettings()),+ fn() => new SettingsResource($this->getSettings())+),+```++4. **Nested Resources**: Transform related objects+```php+'order_items' => OrderItemResource::collection($this->getOrderItems()),+```++5. **Collections**: Use `Resource::collection()` for arrays+```php+'products' => ProductResource::collection($this->getProducts()),+```++## Routing Patterns++**File**: `backend/routes/api.php`++### Route Organization++Routes are organized into three groups:++#### 1. Public Routes (No Authentication)++```php+$router->prefix('/auth')->group(function (Router $router): void {+ $router->post('/login', LoginAction::class)->name('auth.login');+ $router->post('/register', CreateAccountAction::class);+ $router->post('/forgot-password', ForgotPasswordAction::class);+});++$router->prefix('/public')->group(function (Router $router): void {+ $router->get('/events/{event_id}', GetEventPublicAction::class);+ $router->post('/events/{event_id}/order', CreateOrderActionPublic::class);+ $router->get('/organizers/{organizer_id}', GetPublicOrganizerAction::class);+});+```++#### 2. Authenticated Routes (Require JWT)++```php+$router->middleware(['auth:api'])->group(function (Router $router): void {+ // User routes+ $router->get('/users/me', GetMeAction::class);+ $router->post('/users', CreateUserAction::class);++ // Event routes+ $router->post('/events', CreateEventAction::class);+ $router->get('/events/{event_id}', GetEventAction::class);+ $router->put('/events/{event_id}', UpdateEventAction::class);++ // Nested resource routes+ $router->post('/events/{event_id}/products', CreateProductAction::class);+ $router->get('/events/{event_id}/attendees', GetAttendeesAction::class);+});+```++### Common Route Patterns++```php+// CRUD operations+POST /events CreateEventAction+GET /events GetEventsAction+GET /events/{event_id} GetEventAction+PUT /events/{event_id} UpdateEventAction++// Status updates (separate from full updates)+PUT /events/{event_id}/status UpdateEventStatusAction++// Nested resources+POST /events/{event_id}/products CreateProductAction+GET /events/{event_id}/products GetProductsAction+GET /events/{event_id}/products/{id} GetProductAction++// Special actions+POST /events/{event_id}/duplicate DuplicateEventAction+POST /events/{event_id}/orders/export ExportOrdersAction+```++### Naming Conventions++- **Controller-less**: Routes point directly to Action classes+- **REST-like**: Follow RESTful patterns with HTTP verbs+- **Nested Resources**: Parent resource ID in path+- **Named Routes**: Optional for reverse routing++## Request Validation++### BaseRequest++All request classes extend `BaseRequest`:++**File**: `backend/app/Http/Request/BaseRequest.php`++```php+abstract class BaseRequest extends FormRequest+{+}+```++### Simple Validation++**File**: `backend/app/Http/Request/PromoCode/CreateUpdatePromoCodeRequest.php`++```php+class CreateUpdatePromoCodeRequest extends BaseRequest+{+ public function rules(): array+ {+ return [+ 'code' => 'min:2|string|required|max:50',+ 'applicable_product_ids' => 'array',+ 'discount' => [+ 'required_if:discount_type,PERCENTAGE,FIXED',+ 'numeric',+ 'min:0',+ // Custom validation closure+ function ($attribute, $value, $fail) {+ if ($this->input('discount_type') === PromoCodeDiscountTypeEnum::PERCENTAGE->name+ && $value > 100) {+ $fail('The discount percentage must be less than or equal to 100%.');+ }+ },+ ],+ 'expiry_date' => 'date|nullable',+ 'max_allowed_usages' => 'nullable|gte:1|max:9999999',+ 'discount_type' => [+ 'required',+ Rule::in(PromoCodeDiscountTypeEnum::valuesArray())+ ],+ ];+ }+}+```++### Reusable Validation Traits++**File**: `backend/app/Http/Request/Event/CreateEventRequest.php`++```php+class CreateEventRequest extends BaseRequest+{+ use EventRules; // Reusable validation trait++ public function rules(): array+ {+ return $this->eventRules();+ }++ public function messages(): array+ {+ return $this->eventMessages();+ }+}+```++### Validation Features++1. **Laravel Validation Rules**: Standard syntax+2. **Custom Closures**: Inline custom validation+3. **Enum Validation**: `Rule::in(Enum::valuesArray())`+4. **Conditional Rules**: `required_if:field,value`+5. **Custom Messages**: Override via `messages()` method+6. **Reusable Traits**: Share logic across requests++### Automatic Validation++Request validation happens automatically before `__invoke()` is called. Failed validation returns 422 Unprocessable Entity with error details.++## Complete Request Flow++### Example: Create Organizer++**Route**:+```php+$router->post('/organizers', CreateOrganizerAction::class);+```++**Action**: `backend/app/Http/Actions/Organizers/CreateOrganizerAction.php`++```php+class CreateOrganizerAction extends BaseAction+{+ public function __construct(+ private readonly CreateOrganizerHandler $handler+ ) {}++ public function __invoke(UpsertOrganizerRequest $request): JsonResponse+ {+ $organizerData = array_merge(+ $request->validated(),+ ['account_id' => $this->getAuthenticatedAccountId()]+ );++ $organizer = $this->handler->handle(+ organizerData: CreateOrganizerDTO::fromArray($organizerData),+ );++ return $this->resourceResponse(+ resource: OrganizerResource::class,+ data: $organizer,+ statusCode: ResponseCodes::HTTP_CREATED,+ );+ }+}+```++**Request/Response Flow**:++```+POST /api/organizers+Authorization: Bearer {jwt_token}+Content-Type: application/json++{+ "name": "My Organization",+ "email": "[email protected]"+}++β Middleware validates JWT+β UpsertOrganizerRequest validates input+β CreateOrganizerAction invoked+β getAuthenticatedAccountId() retrieves account+β CreateOrganizerHandler creates organizer+β OrganizerResource transforms domain object++HTTP/1.1 201 Created+Content-Type: application/json++{+ "data": {+ "id": 123,+ "name": "My Organization",+ "email": "[email protected]",+ "account_id": 456,+ "created_at": "2025-10-29T..."+ }+}+```++## Best Practices++### 1. Always Extend BaseAction++```php+// β GOOD+class CreateEventAction extends BaseAction+{+ public function __invoke(Request $request): JsonResponse+ {+ return $this->resourceResponse(...);+ }+}++// β BAD+class CreateEventAction+{+ public function __invoke(Request $request): JsonResponse+ {+ return response()->json(['data' => ...]);+ }+}+```++### 2. Use Standardized Response Methods++```php+// β GOOD+return $this->resourceResponse(EventResource::class, $event, ResponseCodes::HTTP_CREATED);++// β BAD+return response()->json(['data' => $event], 201);+```++### 3. Authorize Before Processing++```php+public function __invoke(int $eventId, Request $request): JsonResponse+{+ // Authorization first+ $this->isActionAuthorized($eventId, EventDomainObject::class);++ // Then processing+ $result = $this->handler->handle(...);++ return $this->resourceResponse(...);+}+```++### 4. Convert Domain Exceptions++```php+try {+ $result = $this->handler->handle($dto);+} catch (ResourceConflictException $e) {+ // Convert to Laravel validation exception+ throw ValidationException::withMessages([+ 'code' => $e->getMessage(),+ ]);+} catch (DomainException $e) {+ // Or use error response+ return $this->errorResponse(+ message: $e->getMessage(),+ statusCode: ResponseCodes::HTTP_BAD_REQUEST,+ );+}+```++### 5. Use Type Hints++```php+public function __invoke(+ CreateEventRequest $request, // Type-hinted request+ int $eventId // Type-hinted params+): JsonResponse // Return type+{+ $dto = CreateEventDTO::fromArray($request->validated());+ $event = $this->handler->handle($dto);++ return $this->resourceResponse(EventResource::class, $event);+}+```++## Exception Handling++### Custom Exceptions++```php+class ResourceConflictException extends Exception {}+class EmailTemplateValidationException extends Exception {+ public array $validationErrors = [];+}+class OrderValidationException extends Exception {}+```++### Handler-Level Exception Handling++```php+public function handle(UpsertDTO $dto): DomainObject+{+ try {+ return $this->repository->create([...]);+ } catch (ResourceConflictException $e) {+ throw ValidationException::withMessages([+ 'field' => $e->getMessage(),+ ]);+ }+}+```++### Action-Level Exception Handling++```php+try {+ $result = $this->handler->handle($dto);+} catch (UnauthorizedException $e) {+ return $this->errorResponse(+ message: $e->getMessage(),+ statusCode: ResponseCodes::HTTP_UNAUTHORIZED,+ );+} catch (ValidationException $e) {+ // Laravel handles automatically+ throw $e;+}+```++## Summary++The Hi.Events HTTP layer provides:++1. **Invokable Actions**: Single-purpose action classes extending `BaseAction`+2. **Standardized Responses**: Consistent response methods for all endpoints+3. **Robust Authorization**: Entity-level permission checks via `isActionAuthorized()`+4. **JSON API Resources**: Transform domain objects to API responses+5. **RESTful Routing**: Clear separation of public/authenticated routes+6. **Request Validation**: Laravel FormRequest with reusable traits+7. **Clean Architecture**: Clear boundaries between HTTP, Application, and Domain++**Complete Request Flow**:+```+HTTP Request+ β+Middleware (auth, CORS)+ β+Request Validation+ β+Action (__invoke)+ β+Authorization Check+ β+Handler (orchestration)+ β+Domain Service (business logic)+ β+Repository (data access)+ β+Domain Object (returned)+ β+JSON Resource (transformation)+ β+HTTP Response+```++## Related Documentation++- [Architecture Overview](architecture-overview.md)+- [Domain-Driven Design](domain-driven-design.md)+- [Repository Pattern](repository-pattern.md)+- [Events and Jobs](events-and-jobs.md)diff --git a/backend/docs/architecture-overview.md b/backend/docs/architecture-overview.mdnew file mode 100644index 000000000..01e5486f6--- /dev/null+++ b/backend/docs/architecture-overview.md@@ -0,0 +1,360 @@+# 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++```mermaid+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++```mermaid+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.++```php+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.++```php+interface OrderRepositoryInterface extends RepositoryInterface+{+ public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator;+}+```++### 3. DTO Pattern+Data passed between layers using immutable DTOs.++```php+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.++```php+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.++```php+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**:+```php+$handler->handle(new CreateOrderDTO(...));+```++β **Bad**:+```php+$handler->handle($eventId, $products, $promoCode);+```++### 2. Use Domain Object Constants+Reference fields using constants, not strings.++β **Good**:+```php+$repository->findWhere([OrderDomainObjectAbstract::STATUS => 'COMPLETED']);+```++β **Bad**:+```php+$repository->findWhere(['status' => 'COMPLETED']);+```++### 3. Favor Base Repository Methods+Use existing repository methods before creating custom ones.++β **Good**:+```php+$repository->findFirstWhere(['event_id' => $eventId]);+```++β **Bad**:+```php+$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**:+```php+return $this->resourceResponse(OrderResource::class, $order, ResponseCodes::HTTP_CREATED);+```++β **Bad**:+```php+return response()->json(['data' => $order], 201);+```++### 5. Use Enums for Constants+Define domain constants as enums, not arrays or class constants.++β **Good**:+```php+enum OrderStatus { case COMPLETED; case CANCELLED; }+```++β **Bad**:+```php+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++- [Domain-Driven Design Patterns](domain-driven-design.md)+- [Database Schema Architecture](database-schema.md)+- [Repository Pattern Guide](repository-pattern.md)+- [Events and Jobs System](events-and-jobs.md)+- [API Patterns and HTTP Layer](api-patterns.md)diff --git a/backend/docs/database-schema.md b/backend/docs/database-schema.mdnew file mode 100644index 000000000..756244d6e--- /dev/null+++ b/backend/docs/database-schema.md@@ -0,0 +1,734 @@+# Database Schema Architecture++## Overview++Hi.Events uses PostgreSQL with a multi-tenant architecture built around accounts. The database schema consists of approximately 57 migration files with core schema defined in `database/migrations/schema.sql`.++## Core Entity Hierarchy++```mermaid+graph TB+ A[Account] --> B[User]+ A --> C[Organizer]+ C --> D[Event]+ D --> E[Product/Ticket]+ D --> F[Order]+ F --> G[Attendee]+ E --> H[Product Price]+ F --> I[Order Item]+ D --> J[Questions]+ D --> K[Promo Codes]+ D --> L[Capacity Assignments]+```++## Multi-Tenancy Architecture++### Account-Based Tenancy++```+Account (Tenant)+βββ Users (many-to-many via account_users)+β βββ Role-based permissions+βββ Account Configuration+β βββ Application fees+βββ Taxes and Fees (account-level)+βββ Email Templates (account-level)+βββ Organizers+β βββ Organizer Settings+β βββ Email Templates (organizer-level)+β βββ Events+β βββ Event Settings+β βββ Event Statistics+β βββ Email Templates (event-level)+β βββ Products (Tickets)+β βββ Orders+β βββ Attendees+β βββ Questions+β βββ Promo Codes+β βββ Webhooks+```++### Key Principles++1. **Data Isolation**: Each account's data is isolated via `account_id` foreign key+2. **Hierarchical Structure**: Account β Organizer β Event β Products/Orders+3. **User Access**: Users can belong to multiple accounts with different roles+4. **Cascade Deletes**: Parent deletion cascades to children++## Core Entities++### 1. Account & User Management++#### accounts+Top-level tenant entity.++**Key Fields**:+- `id` - Primary key+- `name` - Account name+- `email` - Account contact email+- `currency_code` - Default currency+- `timezone` - Default timezone+- `stripe_account_id` - Stripe Connect ID+- `stripe_connect_setup_complete` - Onboarding status+- `account_verified_at` - Verification timestamp++**Model**: `app/Models/Account.php`++#### users+User authentication and identity.++**Key Fields**:+- `id` - Primary key+- `email` - Unique email (authentication)+- `password` - Hashed password+- `first_name`, `last_name` - User name+- `timezone` - User timezone+- `email_verified_at` - Email verification+- `status` - User status (ACTIVE/INACTIVE)++**Features**:+- JWT authentication+- Soft deletes+- Can belong to multiple accounts++**Model**: `app/Models/User.php`++#### account_users (Pivot)+Many-to-many relationship with roles.++**Key Fields**:+- `account_id` - Foreign key to accounts+- `user_id` - Foreign key to users+- `role` - User role (ADMIN, ORGANIZER, etc.)+- `is_account_owner` - Owner flag+- `invited_by_user_id` - Invitation tracking+- `status` - Invitation status+- `last_login_at` - Login tracking++**Features**: RBAC (Role-Based Access Control)++#### account_configuration+Account-level configuration for fees.++**Key Fields**:+- `id` - Primary key+- `name` - Configuration name+- `is_system_default` - System default flag+- `application_fees` - JSONB fee structure++**Migration**: `database/migrations/2025_02_16_163546_create_account_configuration.php`++### 2. Event Management++#### organizers+Event organizers (one account can have multiple).++**Key Fields**:+- `id` - Primary key+- `account_id` - Foreign key (CASCADE delete)+- `name` - Organizer name+- `email`, `phone`, `website` - Contact info+- `currency` - Default currency+- `timezone` - Default timezone++**Model**: `app/Models/Organizer.php`++#### events+Core event entity.++**Key Fields**:+- `id` - Primary key+- `account_id` - Foreign key (CASCADE delete)+- `organizer_id` - Foreign key+- `user_id` - Creator+- `title`, `description` - Event details+- `start_date`, `end_date` - Event dates+- `status` - EventStatus enum (DRAFT, LIVE, ARCHIVED)+- `location`, `location_details` - JSONB location data+- `currency`, `timezone` - Event-specific settings+- `short_id` - URL-friendly ID+- `category` - Event category++**Model**: `app/Models/Event.php`++**Relationships**:+- Has many Products, Orders, Attendees, Questions+- Has one EventSettings, EventStatistics+- Belongs to Account, Organizer, User++#### event_settings+Detailed event configuration.++**Key Fields**:+- `event_id` - Primary key (one-to-one)+- `pre_checkout_message`, `post_checkout_message` - Custom messages+- `support_email` - Support contact+- `require_attendee_details` - Attendee form requirement+- `order_timeout_in_minutes` - Reservation timeout+- `homepage_*_color` - Branding colors+- `seo_*` - SEO metadata+- `ticket_design_settings` - JSONB ticket design++**Features**: Complete control over event UX++### 3. Products & Pricing++#### products (formerly tickets)+Tickets/products for events.++**Key Fields**:+- `id` - Primary key+- `event_id` - Foreign key (CASCADE delete)+- `title`, `description` - Product details+- `type` - Product type+- `product_type` - TICKET or OTHER+- `sale_start_date`, `sale_end_date` - Sale window+- `min_per_order`, `max_per_order` - Purchase limits+- `product_category_id` - Category+- `order` - Display order++**Model**: `app/Models/Product.php`++**Migration**: Renamed from `tickets` in `database/migrations/2024_09_20_032323_rename_tickets_to_products.php`++**Relationships**:+- Belongs to Event, ProductCategory+- Has many ProductPrices+- Many-to-many with TaxesAndFees, Questions, CapacityAssignments, CheckInLists++#### product_prices+Multiple pricing tiers per product.++**Key Fields**:+- `id` - Primary key+- `product_id` - Foreign key+- `price` - Price amount+- `label` - Price tier name (e.g., "Early Bird", "VIP")+- `sale_start_date`, `sale_end_date` - Time-based pricing+- `initial_quantity_available` - Starting quantity+- `quantity_sold` - Sold count+- `quantity_available` - Remaining+- `order` - Display order++**Features**:+- Time-based pricing (early bird, etc.)+- Inventory tracking per tier++#### product_categories+Organize products into categories.++**Key Fields**:+- `id` - Primary key+- `event_id` - Foreign key+- `name`, `description` - Category details+- `order` - Display order++#### taxes_and_fees+Account-level tax and fee definitions.++**Key Fields**:+- `id` - Primary key+- `account_id` - Foreign key+- `name` - Tax/fee name+- `type` - TAX or FEE enum+- `calculation_type` - FIXED or PERCENTAGE+- `rate` - Amount/percentage+- `is_active` - Active flag+- `is_default` - Auto-apply to new products++**Features**: Automatically applies default taxes to new tickets++### 4. Orders & Transactions++#### orders+Customer purchases.++**Key Fields**:+- `id` - Primary key+- `short_id`, `public_id` - URL-friendly IDs+- `event_id` - Foreign key+- `first_name`, `last_name`, `email` - Customer info+- `status` - OrderStatus enum (RESERVED, COMPLETED, etc.)+- `payment_status` - Payment state+- `refund_status` - Refund state+- `payment_gateway`, `payment_provider` - Payment method+- `currency` - Order currency+- `total_before_additions` - Subtotal+- `total_tax`, `total_fee` - Tax/fee totals+- `total_gross` - Grand total+- `total_refunded` - Refund amount+- `promo_code_id` - Applied promo code+- `affiliate_id` - Attribution+- `address` - JSONB address+- `taxes_and_fees_rollup` - JSONB tax breakdown+- `point_in_time_data` - JSONB pricing snapshot+- `reserved_until` - Reservation expiry+- `locale` - Order language++**Model**: `app/Models/Order.php`++**Features**:+- GIN trigram indexes on name/email for search+- Point-in-time pricing snapshot+- Order timeout/reservation system++**Relationships**:+- Belongs to Event, PromoCode, Affiliate+- Has many OrderItems, Attendees, Invoices+- Has one StripePayment, OrderApplicationFee++#### order_items+Line items in orders.++**Key Fields**:+- `id` - Primary key+- `order_id` - Foreign key+- `product_id` - Foreign key+- `product_price_id` - Specific price tier+- `quantity` - Item count+- `price` - Unit price+- `price_before_discount` - Pre-discount price+- `total_before_additions` - Subtotal+- `total_tax`, `total_service_fee` - Additions+- `total_gross` - Line total+- `taxes_and_fees_rollup` - JSONB breakdown+- `product_type` - TICKET or OTHER++**Model**: `app/Models/OrderItem.php`++**Features**: No timestamps (immutable once created)++#### stripe_payments+Stripe payment tracking.++**Key Fields**:+- `id` - Primary key+- `order_id` - Foreign key+- `payment_intent_id` - Stripe payment intent+- `charge_id` - Stripe charge+- `payment_method_id` - Payment method+- `amount_received` - Actual amount+- `connected_account_id` - Stripe Connect account+- `last_error` - JSON error details+- `platform` - Stripe platform used++**Model**: `app/Models/StripePayment.php`++#### invoices+Invoice generation for orders.++**Key Fields**:+- `id` - Primary key+- `order_id` - Foreign key+- `account_id` - Foreign key+- `invoice_number` - Unique invoice number+- `issue_date`, `due_date` - Invoice dates+- `total_amount` - Invoice total+- `status` - Invoice status+- `items` - JSONB line items+- `taxes_and_fees` - JSONB tax breakdown+- `uuid` - Public UUID+- `payment_terms`, `notes` - Invoice details++**Model**: `app/Models/Invoice.php`++**Migration**: `database/migrations/2025_01_03_010511_create_invoices_table.php`++### 5. Attendees & Check-Ins++#### attendees+Individual ticket holders.++**Key Fields**:+- `id` - Primary key+- `short_id`, `public_id` - URL-friendly IDs+- `order_id` - Foreign key (CASCADE delete)+- `product_id` - Foreign key (CASCADE delete)+- `product_price_id` - Price tier+- `event_id` - Foreign key (CASCADE delete)+- `first_name`, `last_name`, `email` - Attendee info+- `status` - AttendeeStatus enum+- `locale` - Attendee language+- `notes` - Internal notes++**Model**: `app/Models/Attendee.php`++**Features**:+- GIN trigram indexes for search+- Soft deletes++**Relationships**:+- Belongs to Order, Product, Event+- Has many AttendeeCheckIns, QuestionAnswers++#### check_in_lists+Multiple check-in lists per event.++**Key Fields**:+- `id` - Primary key+- `event_id` - Foreign key+- `short_id` - URL-friendly ID+- `name`, `description` - List details+- `activates_at`, `expires_at` - Active window++**Model**: `app/Models/CheckInList.php`++**Migration**: `database/migrations/2024_08_08_032637_create_check_in_lists_tables.php`++**Features**: Supports multiple entry points or sessions++#### attendee_check_ins+Track individual check-in events.++**Key Fields**:+- `id` - Primary key+- `short_id` - URL-friendly ID+- `check_in_list_id` - Foreign key+- `product_id`, `attendee_id`, `order_id`, `event_id` - References+- `ip_address` - Check-in source++**Model**: `app/Models/AttendeeCheckIn.php`++**Features**: Supports multiple check-ins per attendee++### 6. Questions & Answers++#### questions+Custom form questions.++**Key Fields**:+- `id` - Primary key+- `event_id` - Foreign key+- `title` - Question text+- `type` - QuestionTypeEnum (TEXT, CHECKBOX, etc.)+- `required` - Required flag+- `options` - JSONB options for multiple choice+- `belongs_to` - ORDER or ATTENDEE level+- `order` - Display order+- `is_hidden` - Hidden flag+- `description` - Help text++**Model**: `app/Models/Question.php`++**Relationships**: Many-to-many with Products++#### question_answers+Store answers to questions.++**Key Fields**:+- `id` - Primary key+- `question_id` - Foreign key+- `order_id` - Order-level answer+- `attendee_id` - Attendee-level answer+- `product_id` - Product context+- `answer` - JSONB answer data++**Model**: `app/Models/QuestionAnswer.php`++#### question_and_answer_views (View)+Materialized view for efficient querying.++**Model**: `app/Models/QuestionAndAnswerView.php`++**Purpose**: Pre-joined data for question/answer reporting++### 7. Capacity Management++#### capacity_assignments+Manage capacity limits.++**Key Fields**:+- `id` - Primary key+- `event_id` - Foreign key+- `name` - Capacity name+- `capacity` - Total capacity+- `used_capacity` - Used amount+- `applies_to` - EVENT or PRODUCTS+- `status` - Active status++**Model**: `app/Models/CapacityAssignment.php`++**Migration**: `database/migrations/2024_07_14_031511_create_capacity_assignments_and_associated_tables.php`++**Features**: Share capacity across multiple products++### 8. Promotions & Marketing++#### promo_codes+Discount codes.++**Key Fields**:+- `id` - Primary key+- `event_id` - Foreign key+- `code` - Promo code (indexed)+- `discount` - Discount amount+- `discount_type` - NONE, FIXED, PERCENTAGE+- `applicable_product_ids` - JSONB product restrictions+- `expiry_date` - Expiration+- `max_allowed_usages` - Usage limit+- `attendee_usage_count`, `order_usage_count` - Usage tracking++**Model**: `app/Models/PromoCode.php`++**Features**:+- Product-specific codes+- Usage tracking+- JSONB index on applicable_product_ids++#### affiliates+Affiliate tracking.++**Key Fields**:+- `id` - Primary key+- `event_id`, `account_id` - Foreign keys+- `name` - Affiliate name+- `code` - Unique tracking code (indexed)+- `email` - Contact email+- `total_sales` - Sale count+- `total_sales_gross` - Revenue+- `status` - AffiliateStatus enum++**Model**: `app/Models/Affiliate.php`++**Features**: Attribution tracking for marketing++### 9. Communication++#### email_templates+Customizable email templates.++**Key Fields**:+- `id` - Primary key+- `account_id`, `organizer_id`, `event_id` - Three-level hierarchy+- `template_type` - Template type enum+- `subject`, `body` - Email content+- `cta` - JSON call-to-action+- `engine` - liquid (Liquid template engine)+- `is_active` - Active flag++**Model**: `app/Models/EmailTemplate.php`++**Migration**: `database/migrations/2025_08_28_100704_create_email_templates_table.php`++**Features**: Account β Organizer β Event override hierarchy++#### messages+Bulk messaging to attendees.++**Key Fields**:+- `id` - Primary key+- `event_id` - Foreign key+- `subject`, `message` - Message content+- `type` - Message type+- `recipient_ids`, `product_ids`, `attendee_ids` - JSONB targeting+- `sent_by_user_id` - Sender+- `status` - Send status+- `sent_at` - Sent timestamp++**Model**: `app/Models/Message.php`++### 10. Analytics & Statistics++#### event_statistics+Aggregate statistics per event.++**Key Fields**:+- `event_id` - Primary key (one-to-one)+- `unique_views`, `total_views` - View tracking+- `sales_total_gross`, `sales_total_before_additions` - Revenue+- `total_tax`, `total_fee`, `total_refunded` - Breakdown+- `products_sold` - Sold count+- `orders_created`, `orders_cancelled` - Order metrics+- `attendees_registered` - Attendee count+- `version` - Optimistic locking++**Model**: `app/Models/EventStatistic.php`++**Features**: Optimistic locking via version field++#### event_daily_statistics+Daily breakdown.++**Key Fields**: Same as event_statistics plus `date`++**Model**: `app/Models/EventDailyStatistic.php`++### 11. Webhooks & Integration++#### webhooks+Outgoing webhook configuration.++**Key Fields**:+- `id` - Primary key+- `event_id`, `account_id`, `user_id` - Foreign keys+- `url` - Webhook URL+- `event_types` - JSONB subscribed events+- `status` - WebhookStatus enum+- `secret` - Webhook secret+- `last_response_code`, `last_response_body` - Delivery tracking+- `last_triggered_at` - Last trigger time++**Model**: `app/Models/Webhook.php`++**Migration**: `database/migrations/2025_02_09_074739_create_webhooks_table.php`++#### webhook_logs+Audit log for deliveries.++**Key Fields**:+- `webhook_id` - Foreign key+- `payload` - JSONB payload sent+- `event_type` - Event type+- `response_code`, `response_body` - Response tracking++**Model**: `app/Models/WebhookLog.php`++### 12. Media & Assets++#### images+Polymorphic image storage.++**Key Fields**:+- `id` - Primary key+- `entity_id`, `entity_type` - Polymorphic relation+- `account_id` - Foreign key+- `type` - Image type+- `filename`, `disk`, `path` - Storage details+- `size`, `mime_type` - File metadata++**Model**: `app/Models/Image.php`++**Features**: Attach to any entity via polymorphic relationship++## Key Architectural Patterns++### 1. Soft Deletes+Nearly all entities use soft deletes via `deleted_at` timestamp.++**Benefits**:+- Data recovery+- Audit trails+- Referential integrity++### 2. Timestamps+All tables have `created_at` and `updated_at` (except order_items).++### 3. Foreign Key Cascades++**Common cascade behaviors**:+```sql+-- Event deletion cascades to children+ALTER TABLE products ADD CONSTRAINT FOREIGN KEY (event_id)+ REFERENCES events(id) ON DELETE CASCADE;++-- Order deletion cascades to attendees+ALTER TABLE attendees ADD CONSTRAINT FOREIGN KEY (order_id)+ REFERENCES orders(id) ON DELETE CASCADE;+```++### 4. JSONB for Flexible Data++**Extensive use of PostgreSQL JSONB**:+- `orders.point_in_time_data` - Pricing snapshot+- `orders.taxes_and_fees_rollup` - Tax breakdown+- `orders.address` - Billing/shipping address+- `events.location_details` - Structured location+- `questions.options` - Question choices+- `promo_codes.applicable_product_ids` - Product restrictions+- `invoices.items` - Invoice line items++**Benefits**: Schema flexibility without migrations++### 5. GIN Trigram Indexes++For fast full-text search:++```sql+CREATE INDEX orders_first_name_trgm ON orders+ USING gin(first_name gin_trgm_ops);+```++**Tables**: orders, attendees+**Columns**: first_name, last_name, email, public_id++**PostgreSQL Extension**: pg_trgm (trigram matching)++### 6. Short IDs & Public IDs++User-facing entities use URL-friendly IDs:+- `short_id` - Short identifier+- `public_id` - Public identifier++**Purpose**: Obfuscate internal IDs, friendly URLs++### 7. Optimistic Locking++Event statistics use version field:++```sql+UPDATE event_statistics+SET sales_total = sales_total + 100, version = version + 1+WHERE event_id = 123 AND version = 5;+```++**Prevents**: Race conditions in high-concurrency updates++### 8. Point-in-Time Data++Orders preserve pricing at creation time:++```sql+orders.point_in_time_data = {+ "products": [...],+ "event_settings": {...},+ "promo_code": {...}+}+```++**Benefits**: Historical accuracy after event changes++## Database Technology++### PostgreSQL-Specific Features++1. **JSONB**: Native JSON with indexing+2. **pg_trgm**: Trigram matching for search+3. **Generated Columns**: Auto-incrementing IDs+4. **GIN Indexes**: For JSONB and text search+5. **Database Views**: Complex query optimization+6. **CHECK Constraints**: Enum validation++### Schema Evolution++- **57+ migrations**: Iterative development+- **Major refactors**: tickets β products (2024)+- **Recent additions**: email templates, webhooks, invoices (2025)++## Entity Relationship Summary++```mermaid+erDiagram+ Account ||--o{ User : "has many (via pivot)"+ Account ||--o{ Organizer : "has many"+ Account ||--o{ TaxAndFee : "has many"+ Organizer ||--o{ Event : "has many"+ Event ||--o{ Product : "has many"+ Event ||--o{ Order : "has many"+ Event ||--o{ Question : "has many"+ Event ||--|| EventSettings : "has one"+ Product ||--o{ ProductPrice : "has many"+ Product }o--o{ TaxAndFee : "many-to-many"+ Product }o--o{ Question : "many-to-many"+ Order ||--o{ OrderItem : "has many"+ Order ||--o{ Attendee : "has many"+ Order ||--o| StripePayment : "has one"+ Order ||--o{ Invoice : "has many"+ Attendee ||--o{ AttendeeCheckIn : "has many"+ Attendee ||--o{ QuestionAnswer : "has many"+```++## Related Documentation++- [Architecture Overview](architecture-overview.md)+- [Repository Pattern](repository-pattern.md)+- [Domain-Driven Design](domain-driven-design.md)diff --git a/backend/docs/domain-driven-design.md b/backend/docs/domain-driven-design.mdnew file mode 100644index 000000000..f1e5d9b81--- /dev/null+++ b/backend/docs/domain-driven-design.md@@ -0,0 +1,734 @@+# Domain-Driven Design in Hi.Events++## Overview++Hi.Events implements a clean DDD architecture with clear separation between Application Handlers, Domain Services, and Infrastructure Services. This document explains the patterns, responsibilities, and best practices for each layer.++## Architecture Layers++```mermaid+graph LR+ A[HTTP Action] --> B[Application Handler]+ B --> C[Domain Service]+ C --> D[Repository Interface]+ D --> E[Eloquent Implementation]+ B --> F[Infrastructure Service]+ C --> G[Domain Events]+```++## 1. Application Layer++**Location**: `backend/app/Services/Application/Handlers/`++### Purpose+Orchestration layer that coordinates domain services and handles cross-cutting concerns.++### Responsibilities+- Receive DTOs from HTTP Actions+- Orchestrate multiple domain services+- Manage database transactions+- Handle logging and error management+- Dispatch domain events+- Transform domain objects back to DTOs/responses++### Handler Pattern++Each handler:+- Has a single `handle()` method+- Accepts a DTO as input+- Returns a domain object or DTO+- Uses dependency injection++**Example**: `backend/app/Services/Application/Handlers/Order/MarkOrderAsPaidHandler.php`++```php+class MarkOrderAsPaidHandler+{+ public function __construct(+ private readonly MarkOrderAsPaidService $markOrderAsPaidService,+ private readonly LoggerInterface $logger,+ ) {}++ public function handle(MarkOrderAsPaidDTO $dto): OrderDomainObject+ {+ $this->logger->info(__('Marking order as paid'), [+ 'order_id' => $dto->orderId,+ 'event_id' => $dto->eventId,+ ]);++ return $this->markOrderAsPaidService->markOrderAsPaid(+ $dto->orderId,+ $dto->eventId,+ );+ }+}+```++### Key Characteristics+- **Thin orchestration** - Delegate logic to services+- **Transaction boundaries** - Wrap multi-step operations+- **Event dispatching** - Trigger side effects+- **Error transformation** - Convert domain exceptions++### Naming Convention+- Pattern: `{Action}{Entity}Handler`+- Examples: `CreateOrderHandler`, `UpdateEventHandler`, `DeleteProductHandler`++## 2. Domain Services Layer++**Location**: `backend/app/Services/Domain/`++### Purpose+Core business logic implementation organized by domain concepts.++### Key Domain Areas+- **Order**: Order management, payment processing, cancellation+- **Product**: Product creation, validation, pricing+- **Event**: Event creation, statistics, duplication+- **Auth**: Login, password reset, authentication+- **Payment**: Stripe integration, refunds, webhooks+- **Attendee**: Ticket sending, check-ins+- **Tax**: Tax/fee calculations+- **PromoCode**: Validation and application++### Service Characteristics++```php+class CreateProductService+{+ public function __construct(+ private readonly ProductRepositoryInterface $productRepository,+ private readonly TaxAndProductAssociationService $taxService,+ private readonly ProductPriceCreateService $priceCreateService,+ private readonly HtmlPurifierService $purifier,+ private readonly DomainEventDispatcherService $eventDispatcher,+ ) {}++ public function createProduct(+ ProductDomainObject $product,+ Collection $prices+ ): ProductDomainObject {+ return DB::transaction(function() use ($product, $prices) {+ // 1. Persist product+ $persistedProduct = $this->productRepository->create([+ ProductDomainObjectAbstract::TITLE => $product->getTitle(),+ // ...+ ]);++ // 2. Associate taxes+ $this->taxService->associateTaxesAndFees($persistedProduct->getId());++ // 3. Create prices+ $this->priceCreateService->createPrices($persistedProduct, $prices);++ // 4. Dispatch event+ $this->eventDispatcher->dispatch(+ new ProductEvent(+ type: DomainEventType::PRODUCT_CREATED,+ productId: $persistedProduct->getId()+ )+ );++ return $persistedProduct;+ });+ }+}+```++### Domain Service Guidelines++**DO**:+- Encapsulate business logic+- Focus on single responsibility+- Compose other domain services+- Return domain objects or specialized DTOs+- Throw domain-specific exceptions+- Dispatch domain events++**DON'T**:+- Handle HTTP concerns+- Know about controllers or actions+- Deal with authentication/authorization directly+- Format responses for API++### Naming Conventions+- Action-oriented: `Create*Service`, `Update*Service`, `Delete*Service`+- Process-oriented: `*ProcessingService`, `*CalculationService`+- Utility-oriented: `*ValidationService`, `*ManagementService`++## 3. Data Transfer Objects (DTOs)++**Location**: `backend/app/Services/Application/Handlers/*/DTO/`++### Modern Pattern: BaseDataObject++**Always use** `BaseDataObject` (Spatie Laravel Data) for new DTOs.++```php+class UpsertProductDTO extends BaseDataObject+{+ public function __construct(+ public readonly int $eventId,+ public readonly string $title,+ public readonly ?string $description,+ public readonly ProductType $type,+ /**+ * @var Collection<ProductPriceDTO>+ */+ public readonly Collection $prices,+ public readonly ?int $productCategoryId = null,+ public readonly ?int $maxPerOrder = null,+ ) {}+}+```++### Key Features+- **Constructor promotion**: Concise syntax+- **Readonly properties**: Immutability+- **Type safety**: Enums and primitives+- **Optional parameters**: With defaults+- **Nested DTOs**: Using `Collection` or `#[CollectionOf]`++### Legacy Pattern: BaseDTO++**Deprecated** - Do not use for new code.++```php+// DON'T DO THIS - BaseDTO is deprecated+class OldDTO extends BaseDTO { }++// DO THIS INSTEAD+class NewDTO extends BaseDataObject { }+```++### DTO Best Practices++1. **Always extend BaseDataObject**+```php+class CreateWebhookDTO extends BaseDataObject { }+```++2. **Use readonly properties**+```php+public readonly string $url,+public readonly WebhookStatus $status,+```++3. **Integrate enums directly**+```php+public readonly EmailTemplateEngine $engine = EmailTemplateEngine::LIQUID,+```++4. **Document collections**+```php+/**+ * @var Collection<ProductDTO>+ */+public readonly Collection $products,+```++## 4. Domain Objects++**Location**: `backend/app/DomainObjects/`++### What Are Domain Objects?++Auto-generated, immutable data representations that mirror the database schema.++### Generation Process++```bash+php artisan generate-domain-objects+```++This command:+1. Reads database schema using Doctrine DBAL+2. Generates abstract classes in `Generated/` folder+3. Generates concrete classes (only if they don't exist)++### Structure++**Abstract Class** (`Generated/EventDomainObjectAbstract.php`):+```php+abstract class EventDomainObjectAbstract extends AbstractDomainObject+{+ // Constants for field names+ final public const ID = 'id';+ final public const TITLE = 'title';+ final public const STATUS = 'status';++ // Typed properties+ protected int $id;+ protected string $title;+ protected ?string $status = null;++ // Getters and setters+ public function setId(int $id): self+ {+ $this->id = $id;+ return $this;+ }++ public function getId(): int+ {+ return $this->id;+ }+}+```++**Concrete Class** (`EventDomainObject.php`):+```php+class EventDomainObject extends EventDomainObjectAbstract+{+ private ?Collection $products = null;++ // Custom business logic+ public function isEventInPast(): bool+ {+ return $this->end_date && $this->end_date < now();+ }++ // Relationship accessors+ public function getProducts(): ?Collection+ {+ return $this->products;+ }+}+```++### Usage Pattern++```php+// Use constants for field names+$order = $orderRepository->create([+ OrderDomainObjectAbstract::EVENT_ID => $eventId,+ OrderDomainObjectAbstract::STATUS => OrderStatus::COMPLETED->name,+ OrderDomainObjectAbstract::TOTAL_GROSS => $total,+]);++// Use getters+$orderId = $order->getId();+$status = $order->getStatus();+```++### Best Practices++**DO**:+- Use constants for field names+- Add custom logic to concrete classes+- Use getters/setters for access++**DON'T**:+- Edit abstract classes in `Generated/` folder+- Access properties directly (use getters)+- Forget to regenerate after schema changes++## 5. Enums++**Locations**:+- `backend/app/DomainObjects/Status/` - Status enums+- `backend/app/DomainObjects/Enums/` - General enums++### Status Enums++For entity lifecycle states:++```php+enum OrderStatus+{+ use BaseEnum;++ case RESERVED;+ case CANCELLED;+ case COMPLETED;+ case AWAITING_OFFLINE_PAYMENT;+ case ABANDONED;++ public static function getHumanReadableStatus(string $status): string+ {+ return match ($status) {+ self::RESERVED->name => __('Reserved'),+ self::COMPLETED->name => __('Completed'),+ // ...+ };+ }+}+```++**Examples**:+- `OrderStatus`+- `EventStatus` (DRAFT, LIVE, ARCHIVED)+- `AttendeeStatus`+- `AffiliateStatus`++### General Enums++For domain constants and types:++```php+enum QuestionTypeEnum+{+ use BaseEnum;++ case ADDRESS;+ case PHONE;+ case SINGLE_LINE_TEXT;+ case CHECKBOX;+ case RADIO;+ case DROPDOWN;++ public static function getMultipleChoiceTypes(): array+ {+ return [+ self::CHECKBOX,+ self::MULTI_SELECT_DROPDOWN,+ ];+ }+}+```++**Examples**:+- `TaxType` (TAX, FEE)+- `PromoCodeDiscountTypeEnum`+- `ProductPriceType`+- `MessageTypeEnum`++### BaseEnum Trait++Provides utility methods:++```php+trait BaseEnum+{+ public function getName(): string+ {+ return $this->name;+ }++ public static function valuesArray(): array+ {+ $values = [];+ foreach (self::cases() as $enum) {+ $values[] = $enum->value ?? $enum->name;+ }+ return $values;+ }+}+```++### Usage in Validation++```php+'status' => [+ 'required',+ Rule::in(OrderStatus::valuesArray())+]+```++## 6. DTO Flow Pattern++```mermaid+sequenceDiagram+ participant Action+ participant Handler+ participant Service+ participant Repository++ Action->>Handler: Pass DTO+ Note over Action,Handler: CreateOrderDTO++ Handler->>Service: Extract data, call service+ Note over Handler,Service: Pass primitives/domain objects++ Service->>Repository: Persist data+ Note over Service,Repository: Use domain object constants++ Repository-->>Service: Return Domain Object+ Service-->>Handler: Return Domain Object+ Handler-->>Action: Return Domain Object++ Action->>Action: Transform to Resource+ Note over Action: OrderResource::make($order)+```++### Complete Example: Webhook Creation++**Step 1: Action creates DTO**+```php+$dto = CreateWebhookDTO::from([+ 'url' => $request->input('url'),+ 'eventTypes' => $request->input('event_types'),+ 'eventId' => $eventId,+ 'accountId' => $this->getAuthenticatedAccountId(),+ 'status' => WebhookStatus::ACTIVE,+]);+```++**Step 2: Handler receives DTO**+```php+public function handle(CreateWebhookDTO $dto): WebhookDomainObject+{+ return $this->databaseManager->transaction(+ fn() => $this->createWebhook($dto)+ );+}+```++**Step 3: Handler transforms DTO to Domain Object**+```php+private function createWebhook(CreateWebhookDTO $dto): WebhookDomainObject+{+ $webhookDomainObject = (new WebhookDomainObject())+ ->setUrl($dto->url)+ ->setEventTypes($dto->eventTypes)+ ->setStatus($dto->status->value);++ return $this->createWebhookService->createWebhook($webhookDomainObject);+}+```++**Step 4: Service uses Domain Object**+```php+public function createWebhook(WebhookDomainObject $webhookDO): WebhookDomainObject+{+ $webhook = $this->webhookRepository->create([+ WebhookDomainObjectAbstract::URL => $webhookDO->getUrl(),+ WebhookDomainObjectAbstract::STATUS => $webhookDO->getStatus(),+ WebhookDomainObjectAbstract::SECRET => Str::random(32),+ ]);++ $this->logger->info('Created webhook', ['webhook' => $webhook->toArray()]);++ return $webhook;+}+```++## 7. Transaction Management++### Handler-Level Transactions++Most common pattern - handlers manage transactions:++```php+public function handle(CreateOrderDTO $dto): OrderDomainObject+{+ return $this->databaseManager->transaction(function () use ($dto) {+ $event = $this->eventRepository->findById($dto->eventId);+ $order = $this->orderService->createOrder($event);+ $items = $this->orderItemService->createItems($order, $dto->products);++ return $this->orderService->updateTotals($order, $items);+ });+}+```++### Service-Level Transactions++For complex domain services:++```php+public function markOrderAsPaid(int $orderId, int $eventId): OrderDomainObject+{+ return DB::transaction(function() use ($orderId, $eventId) {+ $order = $this->orderRepository->findById($orderId);++ // Multiple operations atomically+ $this->updateOrderStatus($order);+ $this->updateAttendeeStatuses($order);+ $this->updateProductQuantities($order);+ $this->createInvoice($order);++ // Events dispatched after commit+ OrderStatusChangedEvent::dispatch($order);++ return $order;+ });+}+```++### Transaction Best Practices++1. **Dispatch events after transaction commits**+```php+DB::transaction(function() {+ // DB operations+});+OrderEvent::dispatch($order); // After commit+```++2. **Keep transactions focused**+```php+// DO: Single logical unit of work+DB::transaction(fn() => $this->createOrderWithItems());++// DON'T: Unrelated operations+DB::transaction(function() {+ $this->createOrder();+ $this->sendEmail(); // Side effect, should be async+});+```++3. **Handle failures appropriately**+```php+try {+ DB::transaction(function() {+ // Operations+ });+} catch (DomainException $e) {+ $this->logger->error('Transaction failed', ['error' => $e]);+ throw $e;+}+```++## 8. Service Composition++Services compose other services to handle complex operations:++```php+class CompleteOrderHandler+{+ public function __construct(+ private readonly OrderRepositoryInterface $orderRepository,+ private readonly AttendeeCreationService $attendeeService,+ private readonly QuestionAnswerService $questionService,+ private readonly ProductQuantityUpdateService $quantityService,+ private readonly AffiliateTrackingService $affiliateService,+ private readonly DatabaseManager $db,+ ) {}++ public function handle(string $orderShortId, CompleteOrderDTO $dto): OrderDomainObject+ {+ return $this->db->transaction(function() use ($orderShortId, $dto) {+ $order = $this->orderRepository->findByShortId($orderShortId);++ // Compose multiple services+ $this->attendeeService->createAttendees($order, $dto->products);+ $this->questionService->saveAnswers($order, $dto->answers);+ $this->quantityService->updateQuantities($order);+ $this->affiliateService->trackSale($order);++ return $order;+ });+ }+}+```++## 9. Exception Handling++### Domain Exceptions++Create custom exceptions for domain errors:++```php+class ResourceConflictException extends Exception {}+class EmailTemplateValidationException extends Exception {+ public array $validationErrors = [];+}+class OrderValidationException extends Exception {}+```++### Handler Exception Handling++```php+public function handle(UpsertAffiliateDTO $dto): AffiliateDomainObject+{+ try {+ return $this->affiliateRepository->create([...]);+ } catch (ResourceConflictException $e) {+ throw ValidationException::withMessages([+ 'code' => $e->getMessage(),+ ]);+ }+}+```++### Action Exception Handling++```php+try {+ $result = $this->handler->handle($dto);+} catch (EmailTemplateValidationException $e) {+ return $this->errorResponse(+ message: 'Validation failed',+ statusCode: ResponseCodes::HTTP_BAD_REQUEST,+ errors: $e->validationErrors,+ );+}+```++## 10. Validation Patterns++### Three Levels of Validation++1. **HTTP Layer**: Request validation+```php+class CreateProductRequest extends BaseRequest+{+ public function rules(): array+ {+ return [+ 'title' => 'required|string|max:255',+ 'type' => ['required', Rule::in(ProductType::valuesArray())],+ ];+ }+}+```++2. **Handler Layer**: DTO structure validation+```php+class CreateProductDTO extends BaseDataObject+{+ public function __construct(+ public readonly string $title, // Type validation+ public readonly ProductType $type, // Enum validation+ ) {}+}+```++3. **Domain Layer**: Business rule validation+```php+class OrderValidationService+{+ public function validateOrderCanBeCompleted(OrderDomainObject $order): void+ {+ if ($order->getStatus() === OrderStatus::COMPLETED->name) {+ throw new OrderValidationException('Order already completed');+ }++ if ($order->isExpired()) {+ throw new OrderValidationException('Order has expired');+ }+ }+}+```++## Best Practices Summary++### Handlers Should+- Orchestrate domain services+- Manage transactions at the highest level+- Handle logging and metrics+- Transform between DTOs and domain objects+- Dispatch events+- Handle cross-cutting concerns++### Domain Services Should+- Encapsulate business logic+- Be highly focused (single responsibility)+- Depend on repositories via interfaces+- Compose other domain services+- Return domain objects or specialized DTOs+- Throw domain-specific exceptions++### DTOs Should+- Be immutable (readonly properties)+- Extend BaseDataObject (not BaseDTO)+- Use constructor property promotion+- Integrate enums for type safety+- Document collections with PHPDoc++### Domain Objects Should+- Be auto-generated from schema+- Provide constants for field names+- Have custom logic in concrete classes+- Never be edited in Generated/ folderdiff --git a/backend/docs/events-and-jobs.md b/backend/docs/events-and-jobs.mdnew file mode 100644index 000000000..f8133a222--- /dev/null+++ b/backend/docs/events-and-jobs.md@@ -0,0 +1,860 @@+# Events and Background Jobs Architecture++## Overview++Hi.Events implements a dual-layer event architecture combining Laravel's event system with custom domain events. This enables clean separation between internal workflows (application events) and external integrations (infrastructure events).++```mermaid+graph LR+ A[Domain Service] --> B[Application Event]+ A --> C[Infrastructure Event]+ B --> D[Event Listener]+ C --> E[Webhook Listener]+ D --> F[Background Job]+ E --> F+```++## Architecture Components++### 1. Application Events++**Location**: `backend/app/Events/`++Used for internal domain logic and business workflows.++#### OrderStatusChangedEvent++**File**: `backend/app/Events/OrderStatusChangedEvent.php`++```php+class OrderStatusChangedEvent+{+ use Dispatchable;++ public function __construct(+ public OrderDomainObject $order,+ public bool $sendEmails = true,+ public bool $createInvoice = false,+ ) {}+}+```++**Purpose**: Triggered whenever order status changes (payment received, completion, cancellation).++**Listeners**:+- `SendOrderDetailsEmailListener` - Sends order confirmation+- `CreateInvoiceListener` - Generates invoice+- `UpdateEventStatsListener` - Updates statistics++**Usage**:+```php+OrderStatusChangedEvent::dispatch($order, sendEmails: true, createInvoice: true);+```++#### EventUpdateEvent++**File**: `backend/app/Events/EventUpdateEvent.php`++```php+class EventUpdateEvent+{+ use Dispatchable;++ public function __construct(+ private readonly EventDomainObject $event,+ ) {}+}+```++**Purpose**: Triggered when event details are updated.++**Usage**:+```php+EventUpdateEvent::dispatch($event);+```++### 2. Infrastructure Domain Events++**Location**: `backend/app/Services/Infrastructure/DomainEvents/`++Used for external webhook integrations and system-level events.++#### Event Types++**File**: `backend/app/Services/Infrastructure/DomainEvents/DomainEventType.php`++```php+enum DomainEventType: string+{+ // Product events+ case PRODUCT_CREATED = 'product.created';+ case PRODUCT_UPDATED = 'product.updated';+ case PRODUCT_DELETED = 'product.deleted';++ // Order events+ case ORDER_CREATED = 'order.created';+ case ORDER_UPDATED = 'order.updated';+ case ORDER_MARKED_AS_PAID = 'order.marked_as_paid';+ case ORDER_REFUNDED = 'order.refunded';+ case ORDER_CANCELLED = 'order.cancelled';++ // Attendee events+ case ATTENDEE_CREATED = 'attendee.created';+ case ATTENDEE_UPDATED = 'attendee.updated';+ case ATTENDEE_CANCELLED = 'attendee.cancelled';++ // Check-in events+ case CHECKIN_CREATED = 'checkin.created';+ case CHECKIN_DELETED = 'checkin.deleted';+}+```++#### Event Classes++**Base Event**: `backend/app/Services/Infrastructure/DomainEvents/BaseDomainEvent.php`++```php+abstract class BaseDomainEvent+{+ use Dispatchable;+}+```++**Concrete Events**: All in `backend/app/Services/Infrastructure/DomainEvents/Events/`++**OrderEvent**:+```php+class OrderEvent extends BaseDomainEvent+{+ public function __construct(+ public DomainEventType $type,+ public int $orderId,+ ) {}+}+```++**ProductEvent**:+```php+class ProductEvent extends BaseDomainEvent+{+ public function __construct(+ public DomainEventType $type,+ public int $productId,+ ) {}+}+```++**AttendeeEvent**:+```php+class AttendeeEvent extends BaseDomainEvent+{+ public function __construct(+ public DomainEventType $type,+ public int $attendeeId,+ ) {}+}+```++**CheckinEvent**:+```php+class CheckinEvent extends BaseDomainEvent+{+ public function __construct(+ public DomainEventType $type,+ public int $attendeeCheckinId,+ ) {}+}+```++#### Domain Event Dispatcher++**File**: `backend/app/Services/Infrastructure/DomainEvents/DomainEventDispatcherService.php`++```php+class DomainEventDispatcherService+{+ public function dispatch(BaseDomainEvent $event): void+ {+ try {+ Event::dispatch($event);+ } catch (Exception $e) {+ $this->logger->error('Failed to dispatch domain event', [+ 'event' => get_class($event),+ 'error' => $e->getMessage(),+ ]);+ throw $e;+ }+ }+}+```++**Usage**:+```php+$this->domainEventDispatcher->dispatch(+ new OrderEvent(+ type: DomainEventType::ORDER_CREATED,+ orderId: $order->getId()+ )+);+```++## 3. Event Listeners++**Location**: `backend/app/Listeners/`++Listeners react to events and coordinate side effects.++### Order Listeners++#### SendOrderDetailsEmailListener++**File**: `backend/app/Listeners/Order/SendOrderDetailsEmailListener.php`++```php+class SendOrderDetailsEmailListener+{+ public function handle(OrderStatusChangedEvent $event): void+ {+ if (!$event->sendEmails) {+ return;+ }++ dispatch(new SendOrderDetailsEmailJob($event->order));+ }+}+```++**Pattern**: Checks event flags and dispatches job if appropriate.++#### CreateInvoiceListener++**File**: `backend/app/Listeners/Order/CreateInvoiceListener.php`++```php+class CreateInvoiceListener+{+ public function __construct(+ private readonly InvoiceCreateService $invoiceCreateService+ ) {}++ public function handle(OrderStatusChangedEvent $event): void+ {+ if (!$event->createInvoice) {+ return;+ }++ $order = $event->order;++ if ($order->getStatus() !== OrderStatus::AWAITING_OFFLINE_PAYMENT->name+ && $order->getStatus() !== OrderStatus::COMPLETED->name) {+ return;+ }++ $this->invoiceCreateService->createInvoiceForOrder($order->getId());+ }+}+```++**Pattern**: Uses domain service directly (synchronous operation).++### Event Listeners++#### UpdateEventStatsListener++**File**: `backend/app/Listeners/Event/UpdateEventStatsListener.php`++```php+class UpdateEventStatsListener+{+ public function handle(OrderStatusChangedEvent $event): void+ {+ if (!$event->order->isOrderCompleted()) {+ return;+ }++ dispatch(new UpdateEventStatisticsJob($event->order));+ }+}+```++**Pattern**: Validates conditions before dispatching job.++### Webhook Listener++#### WebhookEventListener++**File**: `backend/app/Listeners/Webhook/WebhookEventListener.php`++```php+class WebhookEventListener+{+ public function handle(BaseDomainEvent $event): void+ {+ $queueName = $this->config->get('queue.webhook_queue_name');++ switch (get_class($event)) {+ case OrderEvent::class:+ DispatchOrderWebhookJob::dispatch(+ orderId: $event->orderId,+ eventType: $event->type,+ )->onQueue($queueName);+ break;++ case AttendeeEvent::class:+ DispatchAttendeeWebhookJob::dispatch(+ attendeeId: $event->attendeeId,+ eventType: $event->type,+ )->onQueue($queueName);+ break;++ case ProductEvent::class:+ DispatchProductWebhookJob::dispatch(+ productId: $event->productId,+ eventType: $event->type,+ )->onQueue($queueName);+ break;++ case CheckinEvent::class:+ DispatchCheckInWebhookJob::dispatch(+ attendeeCheckInId: $event->attendeeCheckinId,+ eventType: $event->type,+ )->onQueue($queueName);+ break;+ }+ }+}+```++**Pattern**: Routes infrastructure events to appropriate webhook jobs on dedicated queue.++## 4. Background Jobs++**Location**: `backend/app/Jobs/`++Jobs implement `ShouldQueue` for asynchronous processing.++### Order Jobs++#### SendOrderDetailsEmailJob++**File**: `backend/app/Jobs/Order/SendOrderDetailsEmailJob.php`++```php+class SendOrderDetailsEmailJob implements ShouldQueue+{+ use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;++ public int $tries = 3;++ public function __construct(+ private readonly OrderDomainObject $order+ ) {}++ public function handle(SendOrderDetailsService $service): void+ {+ $service->sendOrderSummaryAndTicketEmails($this->order);+ }+}+```++**Features**:+- 3 retry attempts+- Automatically queued+- Serializes domain objects++### Webhook Jobs++All webhook jobs follow similar pattern:++**File**: `backend/app/Jobs/Order/Webhook/DispatchOrderWebhookJob.php`++```php+class DispatchOrderWebhookJob implements ShouldQueue+{+ use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;++ public function __construct(+ public int $orderId,+ public DomainEventType $eventType,+ ) {}++ public function handle(WebhookDispatchService $webhookDispatchService): void+ {+ $webhookDispatchService->dispatchOrderWebhook(+ eventType: $this->eventType,+ orderId: $this->orderId,+ );+ }+}+```++**Other Webhook Jobs**:+- `DispatchAttendeeWebhookJob`+- `DispatchProductWebhookJob`+- `DispatchCheckInWebhookJob`++### Event Jobs++#### UpdateEventStatisticsJob++**File**: `backend/app/Jobs/Event/UpdateEventStatisticsJob.php`++```php+class UpdateEventStatisticsJob implements ShouldQueue+{+ use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;++ public int $tries = 5;+ public int $backoff = 10; // seconds++ public function __construct(+ private readonly OrderDomainObject $order+ ) {}++ public function handle(EventStatisticsIncrementService $service): void+ {+ $service->incrementForOrder($this->order);+ }++ public function failed(Throwable $exception): void+ {+ logger()?->error('Failed to update event statistics', [+ 'order' => $this->order->toArray(),+ 'exception' => $exception,+ ]);+ }+}+```++**Features**:+- 5 retry attempts+- 10-second exponential backoff+- Custom failure handler++**Other Event Jobs**:+- `SendEventEmailJob` - Bulk emails to attendees+- `SendMessagesJob` - Batch message processing+- `UpdateEventPageViewsJob` - Page view tracking++### Question Jobs++**File**: `backend/app/Jobs/Question/ExportAnswersJob.php`++Exports survey/question responses.++## 5. Event Registration++**File**: `backend/app/Providers/EventServiceProvider.php`++```php+class EventServiceProvider extends ServiceProvider+{+ private static array $domainEventMap = [+ WebhookEventListener::class => [+ ProductEvent::class,+ OrderEvent::class,+ AttendeeEvent::class,+ CheckinEvent::class,+ ],+ ];++ public function boot(): void+ {+ $this->registerDomainEventListeners();+ }++ private function registerDomainEventListeners(): void+ {+ foreach (self::$domainEventMap as $listener => $events) {+ foreach ($events as $event) {+ Event::listen($event, [$listener, 'handle']);+ }+ }+ }++ public function shouldDiscoverEvents(): bool+ {+ return true; // Auto-discovers Order/Event listeners+ }+}+```++**Registration Strategy**:+- **Manual registration**: Infrastructure domain events β webhook listener+- **Auto-discovery**: Application events β Order/Event listeners (convention-based)++## Event Flow Examples++### Example 1: Order Payment Success++**Trigger**: Stripe payment intent succeeds++**File**: `backend/app/Services/Domain/Payment/Stripe/EventHandlers/PaymentIntentSucceededHandler.php`++```mermaid+sequenceDiagram+ participant Stripe+ participant Handler+ participant DB+ participant AppEvent+ participant InfraEvent+ participant Listener+ participant Job++ Stripe->>Handler: Payment Intent Succeeded+ Handler->>DB: Update order status+ Handler->>DB: Update attendee statuses+ Handler->>DB: Update product quantities+ Handler->>DB: Commit transaction++ Handler->>AppEvent: OrderStatusChangedEvent+ Handler->>InfraEvent: OrderEvent (ORDER_CREATED)++ AppEvent->>Listener: SendOrderDetailsEmailListener+ Listener->>Job: SendOrderDetailsEmailJob++ AppEvent->>Listener: UpdateEventStatsListener+ Listener->>Job: UpdateEventStatisticsJob++ InfraEvent->>Listener: WebhookEventListener+ Listener->>Job: DispatchOrderWebhookJob+```++**Flow**:++1. **Payment Handler** processes Stripe webhook+```php+public function handleEvent(PaymentIntent $paymentIntent): void+{+ $this->databaseManager->transaction(function () use ($paymentIntent) {+ $updatedOrder = $this->updateOrderStatuses($stripePayment);+ $this->updateAttendeeStatuses($updatedOrder);+ $this->quantityUpdateService->updateQuantities($updatedOrder);++ // Dispatch application event+ OrderStatusChangedEvent::dispatch($updatedOrder);++ // Dispatch infrastructure event+ $this->domainEventDispatcherService->dispatch(+ new OrderEvent(+ type: DomainEventType::ORDER_CREATED,+ orderId: $updatedOrder->getId()+ )+ );+ });+}+```++2. **Application Event** triggers 3 listeners:+ - Email listener β Email job+ - Invoice listener β Invoice creation (sync)+ - Statistics listener β Statistics job++3. **Infrastructure Event** triggers:+ - Webhook listener β Webhook job (on dedicated queue)++4. **Background Jobs** execute asynchronously:+ - Email (3 retries)+ - Statistics (5 retries, 10s backoff)+ - Webhook delivery++### Example 2: Manual Order Completion++**Trigger**: User completes order form (no payment required)++```php+public function handle(string $orderShortId, CompleteOrderDTO $dto): OrderDomainObject+{+ $updatedOrder = DB::transaction(function () use ($orderShortId, $dto) {+ $order = $this->getOrder($orderShortId);+ $updatedOrder = $this->updateOrder($order, $dto);+ $this->createAttendees($dto->products, $order);++ if (!$order->isPaymentRequired()) {+ $this->quantityUpdateService->updateQuantities($updatedOrder);+ }++ return $updatedOrder;+ });++ // Dispatch after transaction commits+ OrderStatusChangedEvent::dispatch($updatedOrder);++ if ($updatedOrder->isOrderCompleted()) {+ $this->domainEventDispatcherService->dispatch(+ new OrderEvent(+ type: DomainEventType::ORDER_CREATED,+ orderId: $updatedOrder->getId(),+ )+ );+ }++ return $updatedOrder;+}+```++**Key Pattern**: Events dispatched **after** transaction commits.++## Architectural Patterns++### 1. Dual Event System++**Why Two Systems?**++```+Application Events (app/Events/)+βββ Internal workflows+βββ Business logic triggers+βββ Can be sync or async+βββ Examples: OrderStatusChangedEvent, EventUpdateEvent++Infrastructure Events (Services/Infrastructure/DomainEvents/)+βββ External integrations+βββ Webhook delivery+βββ Always async+βββ Isolated failure domain+βββ Examples: OrderEvent, ProductEvent, AttendeeEvent+```++### 2. Listener Responsibilities++Three distinct patterns:++#### Job Dispatcher (Most Common)++```php+public function handle(OrderStatusChangedEvent $event): void+{+ dispatch(new SendOrderDetailsEmailJob($event->order));+}+```++#### Direct Service Call (Synchronous)++```php+public function handle(OrderStatusChangedEvent $event): void+{+ $this->invoiceCreateService->createInvoiceForOrder($event->order->getId());+}+```++#### Router/Multiplexer++```php+public function handle(BaseDomainEvent $event): void+{+ switch (get_class($event)) {+ case OrderEvent::class:+ DispatchOrderWebhookJob::dispatch(...)->onQueue('webhooks');+ break;+ }+}+```++### 3. Job Design Patterns++**Retry Strategy**:+```php+// User-facing operations - fail fast+public int $tries = 3;++// Background statistics - eventual consistency OK+public int $tries = 5;+public int $backoff = 10; // seconds+```++**Failure Handling**:+```php+public function failed(Throwable $exception): void+{+ logger()->error('Job failed', [+ 'job' => static::class,+ 'data' => $this->data,+ 'exception' => $exception,+ ]);+}+```++**Serialization**:+```php+// Domain objects auto-serialized+public function __construct(+ private readonly OrderDomainObject $order // SerializesModels trait+) {}++// Or use primitive IDs for smaller payload+public function __construct(+ public int $orderId,+ public DomainEventType $eventType,+) {}+```++### 4. Transaction Boundaries++**Critical Pattern**: Events dispatched **after** DB transaction commits.++```php+// β GOOD - Events after commit+DB::transaction(function() {+ // DB operations+});+OrderStatusChangedEvent::dispatch($order);++// β BAD - Events inside transaction+DB::transaction(function() {+ // DB operations+ OrderStatusChangedEvent::dispatch($order); // May see uncommitted data+});+```++**Benefits**:+- Listeners see committed data+- Prevents duplicate processing on rollback+- Maintains referential integrity++### 5. Event Discovery vs Manual Registration++**Auto-discovered** (convention: `app/Listeners/{Domain}/{EventName}Listener.php`):+```+app/Listeners/Order/SendOrderDetailsEmailListener.php β OrderStatusChangedEvent+app/Listeners/Event/UpdateEventStatsListener.php β OrderStatusChangedEvent+```++**Manually registered** (cross-cutting concerns):+```php+private static array $domainEventMap = [+ WebhookEventListener::class => [+ ProductEvent::class,+ OrderEvent::class,+ AttendeeEvent::class,+ ],+];+```++## Best Practices++### 1. Choose the Right Event Type++**Use Application Events when**:+- Internal workflow coordination+- Multiple side effects needed+- May be sync or async+- Example: Order status changes β emails, invoices, stats++**Use Infrastructure Events when**:+- External integrations+- Webhook delivery+- Always async+- Isolated failure domain+- Example: Notify external systems of order creation++### 2. Keep Listeners Thin++```php+// β GOOD - Listener dispatches job+public function handle(OrderStatusChangedEvent $event): void+{+ if ($event->sendEmails) {+ dispatch(new SendOrderDetailsEmailJob($event->order));+ }+}++// β BAD - Business logic in listener+public function handle(OrderStatusChangedEvent $event): void+{+ $email = new OrderConfirmationEmail($event->order);+ Mail::send($email); // Blocking operation+}+```++### 3. Use Conditional Dispatch++```php+// Conditional based on event state+if ($event->sendEmails) {+ dispatch(new SendEmailJob($order));+}++// Conditional based on domain object+if ($order->isOrderCompleted()) {+ dispatch(new UpdateStatisticsJob($order));+}+```++### 4. Queue Separation++```php+// High-priority user-facing+SendOrderDetailsEmailJob::dispatch($order)->onQueue('emails');++// Lower-priority background+UpdateEventStatisticsJob::dispatch($order)->onQueue('stats');++// Separate failure domain+DispatchOrderWebhookJob::dispatch(...)->onQueue('webhooks');+```++### 5. Error Handling++```php+class UpdateEventStatisticsJob implements ShouldQueue+{+ public int $tries = 5;+ public int $backoff = 10;++ public function handle(EventStatisticsService $service): void+ {+ $service->incrementForOrder($this->order);+ }++ public function failed(Throwable $exception): void+ {+ logger()->error('Statistics update failed', [+ 'order_id' => $this->order->getId(),+ 'error' => $exception->getMessage(),+ ]);++ // Optionally: send alert, log to external service, etc.+ }+}+```++## Summary++Hi.Events implements a sophisticated event-driven architecture:++**Components**:+- 3 application events (internal workflows)+- 4 infrastructure event classes + 13 event types (webhooks)+- 10 background jobs (async processing)+- 7 event listeners (orchestration)++**Strengths**:+- Clear separation of concerns (internal vs external events)+- Transactional safety (events after commits)+- Extensible via auto-discovery+- Robust retry/failure handling+- Queue isolation prevents cascading failures++**Total Architecture**:+```+Domain Service β Event Dispatch+ β+ ββββββββββββββ΄βββββββββββββ+ β β+Application Event Infrastructure Event+ β β+Event Listener Webhook Listener+ β β+Background Job Webhook Job+ β β+ Send Email External System+ Update Stats+ Generate Invoice+```++## Related Documentation++- [Architecture Overview](architecture-overview.md)+- [Domain-Driven Design](domain-driven-design.md)+- [Repository Pattern](repository-pattern.md)diff --git a/backend/docs/repository-pattern.md b/backend/docs/repository-pattern.mdnew file mode 100644index 000000000..e523d29a5--- /dev/null+++ b/backend/docs/repository-pattern.md@@ -0,0 +1,604 @@+# Repository Pattern in Hi.Events++## Overview++Hi.Events uses a clean implementation of the Repository Pattern that provides abstraction between the domain layer and data persistence. All repositories follow interface-based design and return domain objects instead of Eloquent models.++## Architecture++```mermaid+graph TB+ A[Handler] --> B[Repository Interface]+ B --> C[Eloquent Repository Implementation]+ C --> D[Eloquent Model]+ D --> E[Database]+ C --> F[Domain Object]+ F --> A+```++## Core Components++### 1. Base Repository Interface++**Location**: `backend/app/Repository/Interfaces/RepositoryInterface.php`++Provides 40+ methods for common CRUD operations:++#### Core CRUD Methods++```php+// Create+public function create(array $attributes): DomainObjectInterface;+public function insert(array $inserts): bool; // Bulk insert++// Read+public function all(array $columns = ['*']): Collection;+public function findById(int $id, array $columns = ['*']): DomainObjectInterface;+public function findFirst(int $id, array $columns = ['*']): ?DomainObjectInterface;+public function findWhere(array $where, array $columns = ['*']): Collection;+public function findFirstWhere(array $where, array $columns = ['*']): ?DomainObjectInterface;+public function findWhereIn(string $field, array $values): Collection;++// Update+public function updateFromDomainObject(int $id, DomainObjectInterface $do): DomainObjectInterface;+public function updateFromArray(int $id, array $attributes): DomainObjectInterface;+public function updateWhere(array $attributes, array $where): int;++// Delete+public function deleteById(int $id): bool;+public function deleteWhere(array $conditions): int;+```++#### Pagination & Counting++```php+public function paginate(int $limit = 20, array $columns = ['*']): LengthAwarePaginator;+public function paginateWhere(array $where, int $limit = 20): LengthAwarePaginator;+public function countWhere(array $conditions): int;+```++#### Increment/Decrement++```php+public function increment(int $id, string $column, int|float $amount = 1): int;+public function decrement(int $id, string $column, int|float $amount = 1): int;+public function incrementWhere(array $where, string $column, int|float $amount = 1): int;+```++#### Special Operations++```php+// Eager loading+public function loadRelation(string|Relationship $relationship): static;++// Include soft deleted+public function includeDeleted(): static;++// Required domain object mapping+public function getDomainObject(): string; // Returns FQCN of domain object+```++### 2. Base Repository Implementation++**Location**: `backend/app/Repository/Eloquent/BaseRepository.php`++Abstract class that implements all interface methods with:+- Automatic model hydration to domain objects+- Flexible where conditions+- Model reset pattern+- Eager loading support++#### Key Implementation Features++**Flexible Where Conditions**:++```php+// Simple key-value+$where = ['event_id' => 1];++// Array with operator+$where = [['status', '!=', 'RESERVED']];++// Callable for complex queries+$where[] = static function (Builder $builder) {+ $builder->where('name', 'like', '%search%')+ ->orWhere('email', 'like', '%search%');+};+```++**Automatic Hydration**:++```php+private function hydrateDomainObjectFromModel(Model $model): DomainObjectInterface+{+ $domainObject = new ($this->getDomainObject())();++ foreach ($model->attributesToArray() as $attribute => $value) {+ $method = 'set' . ucfirst(Str::camel($attribute));+ if (is_callable([$domainObject, $method])) {+ $domainObject->$method($value);+ }+ }++ // Handle eager-loaded relationships+ $this->handleEagerLoads($model, $domainObject);++ return $domainObject;+}+```++## Creating a Repository++### Step 1: Define Interface++**File**: `backend/app/Repository/Interfaces/AffiliateRepositoryInterface.php`++```php+<?php++namespace HiEvents\Repository\Interfaces;++use HiEvents\DomainObjects\AffiliateDomainObject;+use HiEvents\DataTransferObjects\QueryParamsDTO;+use Illuminate\Pagination\LengthAwarePaginator;++interface AffiliateRepositoryInterface extends RepositoryInterface+{+ public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator;++ public function incrementSales(int $affiliateId, float $amount): void;+}+```++### Step 2: Create Implementation++**File**: `backend/app/Repository/Eloquent/AffiliateRepository.php`++```php+<?php++namespace HiEvents\Repository\Eloquent;++use HiEvents\DomainObjects\AffiliateDomainObject;+use HiEvents\DomainObjects\Generated\AffiliateDomainObjectAbstract;+use HiEvents\Models\Affiliate;+use HiEvents\Repository\Interfaces\AffiliateRepositoryInterface;+use Illuminate\Database\Query\Builder;++class AffiliateRepository extends BaseRepository implements AffiliateRepositoryInterface+{+ protected function getModel(): string+ {+ return Affiliate::class; // Eloquent model+ }++ public function getDomainObject(): string+ {+ return AffiliateDomainObject::class; // Domain object returned+ }++ public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator+ {+ $where = [+ [AffiliateDomainObjectAbstract::EVENT_ID, '=', $eventId]+ ];++ // Add search if query provided+ if ($params->query) {+ $where[] = static function (Builder $builder) use ($params) {+ $builder+ ->orWhere(AffiliateDomainObjectAbstract::NAME, 'ilike', '%' . $params->query . '%')+ ->orWhere(AffiliateDomainObjectAbstract::CODE, 'ilike', '%' . $params->query . '%')+ ->orWhere(AffiliateDomainObjectAbstract::EMAIL, 'ilike', '%' . $params->query . '%');+ };+ }++ $this->model = $this->model->orderBy(+ column: $params->sort_by ?? AffiliateDomainObject::getDefaultSort(),+ direction: $params->sort_direction ?? 'desc',+ );++ return $this->paginateWhere(+ where: $where,+ limit: $params->per_page,+ page: $params->page,+ );+ }++ public function incrementSales(int $affiliateId, float $amount): void+ {+ $this->model->where('id', $affiliateId)+ ->increment('total_sales', 1, [+ 'total_sales_gross' => $this->db->raw('total_sales_gross + ' . $amount)+ ]);+ }+}+```++### Step 3: Register in Service Provider++**File**: `backend/app/Providers/RepositoryServiceProvider.php`++```php+class RepositoryServiceProvider extends ServiceProvider+{+ private static array $interfaceToConcreteMap = [+ AffiliateRepositoryInterface::class => AffiliateRepository::class,+ OrderRepositoryInterface::class => OrderRepository::class,+ EventRepositoryInterface::class => EventRepository::class,+ // ... more mappings+ ];++ public function register(): void+ {+ foreach (self::$interfaceToConcreteMap as $interface => $concrete) {+ $this->app->bind($interface, $concrete);+ }+ }+}+```++## Usage in Handlers++### Basic Usage++```php+class CreateAffiliateHandler+{+ public function __construct(+ private readonly AffiliateRepositoryInterface $affiliateRepository,+ ) {}++ public function handle(int $eventId, int $accountId, UpsertAffiliateDTO $dto): AffiliateDomainObject+ {+ // Check for existing+ $existing = $this->affiliateRepository->findFirstWhere([+ 'event_id' => $eventId,+ 'code' => $code,+ ]);++ if ($existing) {+ throw new ResourceConflictException('Affiliate with this code already exists');+ }++ // Create new affiliate+ return $this->affiliateRepository->create([+ 'event_id' => $eventId,+ 'account_id' => $accountId,+ 'name' => $dto->name,+ 'code' => $code,+ 'email' => $dto->email,+ 'status' => $dto->status->value,+ ]);+ }+}+```++### Using Domain Object Constants++**Always use constants** for field names:++```php+// β GOOD - Using constants+$affiliate = $this->affiliateRepository->findFirstWhere([+ AffiliateDomainObjectAbstract::EVENT_ID => $eventId,+ AffiliateDomainObjectAbstract::CODE => $code,+ AffiliateDomainObjectAbstract::STATUS => AffiliateStatus::ACTIVE->value,+]);++// β BAD - Using strings+$affiliate = $this->affiliateRepository->findFirstWhere([+ 'event_id' => $eventId,+ 'code' => $code,+]);+```++### Eager Loading++```php+$event = $this->eventRepository+ ->loadRelation(EventSettingDomainObject::class)+ ->loadRelation(EventStatisticDomainObject::class)+ ->findById($eventId);++// Event now has eager-loaded settings and statistics+$settings = $event->getEventSettings();+$statistics = $event->getEventStatistics();+```++### Complex Queries++```php+public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator+{+ $where = [+ [OrderDomainObjectAbstract::EVENT_ID, '=', $eventId],+ [OrderDomainObjectAbstract::STATUS, '!=', OrderStatus::RESERVED->name],+ ];++ // Complex search with OR conditions+ if ($params->query) {+ $where[] = static function (Builder $builder) use ($params) {+ $builder+ ->where(+ DB::raw("(first_name||' '||last_name)"),+ 'ilike',+ '%' . $params->query . '%'+ )+ ->orWhere(OrderDomainObjectAbstract::EMAIL, 'ilike', '%' . $params->query . '%')+ ->orWhere(OrderDomainObjectAbstract::PUBLIC_ID, 'ilike', '%' . $params->query . '%');+ };+ }++ // Dynamic filters+ if (!empty($params->filter_fields)) {+ $this->applyFilterFields($params, OrderDomainObject::getAllowedFilterFields());+ }++ // Sorting+ $this->model = $this->model->orderBy(+ column: $params->sort_by ?? OrderDomainObject::getDefaultSort(),+ direction: $params->sort_direction ?? 'desc',+ );++ return $this->paginateWhere($where, $params->per_page, page: $params->page);+}+```++### Relationship Constraints++```php+public function findOrdersAssociatedWithProducts(+ int $eventId,+ array $productIds,+ array $orderStatuses+): Collection {+ return $this->handleResults(+ $this->model+ ->whereHas('order_items', static function (Builder $query) use ($productIds) {+ $query->whereIn('product_id', $productIds);+ })+ ->whereIn('status', $orderStatuses)+ ->where('event_id', $eventId)+ ->get()+ );+}+```++## Best Practices++### 1. Favor Base Methods Over Custom Methods++**Prefer existing base methods**:++```php+// β GOOD - Use base method+$affiliate = $repository->findFirstWhere(['event_id' => $eventId]);++// β BAD - Custom method for common pattern+$affiliate = $repository->findByEventId($eventId);+```++Only create custom methods for **complex, reusable queries**:++```php+// β GOOD - Complex query worth a custom method+public function findOrdersAssociatedWithProducts(+ int $eventId,+ array $productIds,+ array $orderStatuses+): Collection;++// β GOOD - Domain-specific business logic+public function incrementSales(int $affiliateId, float $amount): void;+```++### 2. Use Type Hints++```php+public function handle(int $eventId, UpsertDTO $dto): AffiliateDomainObject+{+ // Handler knows it receives a domain object+ $affiliate = $this->repository->create([...]);++ // Type-safe method calls+ $affiliateId = $affiliate->getId();+ $status = $affiliate->getStatus();++ return $affiliate;+}+```++### 3. Handle Null Safely++```php+// findById throws if not found+$affiliate = $this->repository->findById($id);++// findFirstWhere returns null if not found+$affiliate = $this->repository->findFirstWhere(['code' => $code]);++if (!$affiliate) {+ throw new NotFoundHttpException('Affiliate not found');+}+```++### 4. Use Transactions at Handler Level++```php+public function handle(CreateOrderDTO $dto): OrderDomainObject+{+ return $this->databaseManager->transaction(function () use ($dto) {+ // Multiple repository calls in transaction+ $event = $this->eventRepository->findById($dto->eventId);+ $order = $this->orderRepository->create([...]);+ $items = $this->orderItemRepository->insert([...]);++ return $order;+ });+}+```++### 5. Avoid N+1 Queries++```php+// β GOOD - Eager load relationships+$orders = $this->orderRepository+ ->loadRelation(OrderItemDomainObject::class)+ ->loadRelation(AttendeeDomainObject::class)+ ->findWhere(['event_id' => $eventId]);++// β BAD - N+1 query+$orders = $this->orderRepository->findWhere(['event_id' => $eventId]);+foreach ($orders as $order) {+ $items = $order->getOrderItems(); // Lazy load for each order+}+```++## Common Repository Patterns++### Pagination with Filters++```php+public function findByEventId(int $eventId, QueryParamsDTO $params): LengthAwarePaginator+{+ $where = [['event_id', '=', $eventId]];++ if ($params->query) {+ $where[] = static fn($builder) => $builder->where('name', 'ilike', '%' . $params->query . '%');+ }++ if ($params->filter_fields) {+ $this->applyFilterFields($params, DomainObject::getAllowedFilterFields());+ }++ $this->model = $this->model->orderBy(+ $params->sort_by ?? 'created_at',+ $params->sort_direction ?? 'desc'+ );++ return $this->paginateWhere($where, $params->per_page, page: $params->page);+}+```++### Bulk Operations++```php+// Bulk insert+$this->repository->insert([+ ['name' => 'Item 1', 'event_id' => 1],+ ['name' => 'Item 2', 'event_id' => 1],+]);++// Bulk update+$this->repository->updateWhere(+ ['status' => 'CANCELLED'],+ ['event_id' => 1, 'payment_status' => 'PENDING']+);++// Bulk delete+$this->repository->deleteWhere(['status' => 'EXPIRED']);+```++### Increment/Decrement++```php+// Increment single field+$this->repository->increment($id, 'view_count', 1);++// Increment with additional updates+$this->model->where('id', $affiliateId)+ ->increment('total_sales', 1, [+ 'total_sales_gross' => DB::raw('total_sales_gross + ' . $amount)+ ]);+```++### Finding by Short ID++```php+public function findByShortId(string $orderShortId): ?OrderDomainObject+{+ return $this->findFirstByField('short_id', $orderShortId);+}+```++## Testing Repositories++### Unit Testing with Mocks++```php+use Mockery;+use Tests\TestCase;++class CreateAffiliateHandlerTest extends TestCase+{+ use DatabaseTransactions;++ public function test_creates_affiliate_successfully(): void+ {+ $repository = Mockery::mock(AffiliateRepositoryInterface::class);++ $repository->shouldReceive('findFirstWhere')+ ->once()+ ->with(['event_id' => 1, 'code' => 'TEST'])+ ->andReturn(null);++ $repository->shouldReceive('create')+ ->once()+ ->with([+ 'event_id' => 1,+ 'name' => 'Test Affiliate',+ 'code' => 'TEST',+ ])+ ->andReturn(new AffiliateDomainObject());++ $handler = new CreateAffiliateHandler($repository);+ $result = $handler->handle(1, 1, new UpsertAffiliateDTO(...));++ $this->assertInstanceOf(AffiliateDomainObject::class, $result);+ }+}+```++## Repository Method Reference++### Query Methods++| Method | Returns | Description |+|--------|---------|-------------|+| `all()` | Collection | Get all records |+| `findById()` | DomainObject | Find by ID (throws if not found) |+| `findFirst()` | ?DomainObject | Find by ID (returns null if not found) |+| `findWhere()` | Collection | Find multiple by conditions |+| `findFirstWhere()` | ?DomainObject | Find first by conditions |+| `findWhereIn()` | Collection | Find where column in array |+| `paginate()` | LengthAwarePaginator | Paginate all |+| `paginateWhere()` | LengthAwarePaginator | Paginate with conditions |+| `countWhere()` | int | Count matching records |++### Mutation Methods++| Method | Returns | Description |+|--------|---------|-------------|+| `create()` | DomainObject | Create single record |+| `insert()` | bool | Bulk insert (no domain objects returned) |+| `updateFromArray()` | DomainObject | Update by ID with array |+| `updateFromDomainObject()` | DomainObject | Update by ID with domain object |+| `updateWhere()` | int | Bulk update matching records |+| `deleteById()` | bool | Delete by ID |+| `deleteWhere()` | int | Bulk delete matching records |++### Utility Methods++| Method | Returns | Description |+|--------|---------|-------------|+| `increment()` | int | Increment column |+| `decrement()` | int | Decrement column |+| `loadRelation()` | self | Add eager load (chainable) |+| `includeDeleted()` | self | Include soft deleted (chainable) |++## Related Documentation++- [Architecture Overview](architecture-overview.md)+- [Domain-Driven Design](domain-driven-design.md)+- [Database Schema](database-schema.md)