Skip to content

CLAUDE.md

Latest commit

 

History

History
130 lines (99 loc) · 5.35 KB

CLAUDE.md

File metadata and controls

130 lines (99 loc) · 5.35 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Hi.Events is an open-source event management and ticketing platform with a Laravel backend and React frontend, using Domain-Driven Design (DDD).

Key Commands

Backend (Laravel)

Commands must be executed in the backend docker container:

cd docker/development

docker compose -f docker-compose.dev.yml exec backend php artisan migrate
docker compose -f docker-compose.dev.yml exec backend php artisan generate-domain-objects
docker compose -f docker-compose.dev.yml exec backend php artisan test
docker compose -f docker-compose.dev.yml exec backend php artisan test --filter=TestName
docker compose -f docker-compose.dev.yml exec backend php artisan test --testsuite=Unit
docker compose -f docker-compose.dev.yml exec backend ./vendor/bin/pint --test

Frontend (React + Vite) - SSR Only

cd frontend
yarn install
yarn dev:ssr              # Development server
yarn build                # SSR build
yarn messages:extract     # Extract translatable strings
yarn messages:compile     # Compile translations
npx tsc --noEmit          # TypeScript validation

Docker Development

cd docker/development
./start-dev.sh                     # Unsigned SSL certs
./start-dev.sh --certs=signed      # Signed certs with mkcert

Development Guidelines

Backend

Architecture Flow

  • Request flow: Action → Handler → Domain Service → Repository
  • Handlers can use repositories directly when a service would be overkill
  • No Eloquent in handlers or services — Eloquent belongs in repositories only
  • Favour composition over inheritance
  • Keep code clean, but don't be dogmatic about it

General Standards

  • ALWAYS wrap all translatable strings in __() helper
  • Domain Objects are auto-generated via php artisan generate-domain-objects - never edit manually
  • Always create unit tests for new features in backend/tests/Unit/
  • DON'T add comments unless absolutely necessary
  • ALWAYS sanitize user-provided content with HtmlPurifierService before storing, especially content rendered as HTML

DTOs

  • Use Spatie Laravel Data package for all new DTOs
  • ALWAYS extend BaseDataObject, not BaseDTO
  • ALWAYS favor DTOs over arrays when returning multiple values from services

HTTP Actions

  • Always extend BaseAction.php
  • ALWAYS use BaseAction response methods: resourceResponse(), jsonResponse(), errorResponse(), deletedResponse(), etc. Never use response()->json() or new JsonResponse() directly
  • Always use isActionAuthorized for non-public endpoints
  • DON'T create actions handling multiple entity types with optional parameters - create separate, focused actions instead
  • DO use base classes to share common validation and logic

Exception Handling

  • DON'T use generic exceptions like InvalidArgumentException and RuntimeException
  • DO use custom exceptions (e.g., EmailTemplateValidationException, ResourceConflictException)
  • DO catch custom exceptions in actions and convert to ValidationException::withMessages() or appropriate error responses

Repository Pattern

  • Favour existing repository methods over creating bespoke ones. E.g., use findFirstWhere(['event_id' => $eventId]) instead of creating findByEventId

Database & Migrations

  • DO use auto-incrementing integer IDs ($table->id()), not UUIDs
  • Use anonymous class syntax for migrations

Enums

  • Status enums go in backend/app/DomainObjects/Status/
  • Other enums go in backend/app/DomainObjects/Enums/

Testing

  • DON'T use RefreshDatabase - use DatabaseTransactions instead
  • Unit tests extend Laravel's TestCase, not PHPUnit's TestCase
  • Use Mockery for mocking

Frontend

General Standards

  • This is a SSR app - ensure safe usage of window and document objects
  • Favour using existing components over creating new ones
  • DON'T include unnecessary React imports
  • ALWAYS add translations when adding new user-facing strings - use Lingui t function or Trans component
  • IMMEDIATELY after adding translatable strings, add translations for all supported languages (use /translations skill for the workflow)

Data Fetching

  • Use React Query for all API interactions
  • Query example: frontend/src/queries/useGetCapacityAssignment.ts
  • Mutation example: frontend/src/mutations/useCreateAffiliate.ts

UI & Styling

  • Use Mantine UI components for UI elements
  • Prefer SCSS modules over Mantine layout components for layout styling

Error Handling

  • DON'T use showNotification from @mantine/notifications
  • DO use showSuccess, showError from frontend/src/utilites/notifications.tsx
  • DO use useFormErrorResponseHandler from frontend/src/hooks/useFormErrorResponseHandler.tsx for validation errors
  • DO handle errors in parent components, not in reusable components

Development Workflows

Database Changes (in Backend Container)

  1. Create migration: php artisan make:migration create_XXX_table
  2. Run migration: php artisan migrate
  3. Regenerate Domain Objects: php artisan generate-domain-objects

Before Finalizing Changes

  1. Frontend: cd frontend && npx tsc --noEmit
  2. Backend: docker compose -f docker-compose.dev.yml exec backend php artisan test --testsuite=Unit