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.

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

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

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

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

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

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

1. Read: Architecture Overview - Understand the layers
2. Read: Domain-Driven Design - Understand DTOs, Handlers, Services
3. Reference: Existing feature in /prompts directory
4. Implement: Following the established patterns

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
5. Register repository: Add to RepositoryServiceProvider
6. Update database docs: Reference Database Schema

1. Create FormRequest: See API Patterns
2. Create Action: Extend BaseAction, see API Patterns
3. Create DTO: Extend BaseDataObject, see DDD
4. Create Handler: See DDD
5. Create Domain Service (if needed): See DDD
6. Create JSON Resource: See API Patterns
7. Add route: routes/api.php

1. Create Event: See Events and Jobs
2. Create Job: See Events and Jobs
3. Create Listener: See Events and Jobs
4. Register (if needed): See Events and Jobs

# 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

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

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

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

• 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

• CLAUDE.md - Project guidelines for AI assistants
• Laravel Documentation
• Spatie Laravel Data
• PostgreSQL Documentation

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

1. Start with: Architecture Overview
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.0