AGENTS.md

Project information

Bar Assistant is all-in-one solution for managing your home bar. Compared to other recipe management software that usually tries to be more for general use, Bar Assistant is made specifically for managing cocktail recipes.

Architecture

• PHP 8.4, SQLite, Redis (cache), Optional queue via Laravel Horizon
• Development environment is run via docker compose stack
  • Service app runs the API
  • This means you need to prefix php commands with docker compose exec app
• OpenAPI is used to document the API endpoints
• Database: SQLite located at ./storage/bar-assistant/database.ba3.sqlite

Folder structure

• Folder app contains the complete Laravel application and is considered as a legacy infrastrucutre layer
  • Code written there should follow standard Laravel best practices
• Folder src is a new code that will follow Domain Driven Design and hexagonal architecture principles
• Folder tests contains tests
  • Unit tests are located in tests/Unit
  • Feature tests (laravel HTTP testing) are located in tests/Feature

System requirements (non-discoverable)

• The image processing library jcupitt/vips requires:
  • System package libvips42 (CI installs it via apt-get install libvips42)
  • PHP FFI extension enabled (ffi.enable=true)
  • Raised stack size: zend.max_allowed_stack_size=-1 (prevents stack overflow in FFI calls)
• Without these, image upload/processing tests and functionality will fail silently or crash.

OpenAPI caveat

• composer openapi generates OpenAPI docs by scanning the app/ directory only. New endpoints written in src/ (DDD layer) will not appear in the generated spec unless you also register them in app/.
• CI runs Spectral to lint the generated OpenAPI YAML.

Commands

# Run static analysis (level: max)
docker compose exec app vendor/bin/phpstan analyse

# Automatically fix code style issues
docker compose exec app vendor/bin/pint

# Run the full test suite
docker compose exec app vendor/bin/phpunit

# Run a single test class
docker compose exec app vendor/bin/phpunit tests/Unit/UtilsTest.php

# Run tests (Laravel wrapper — CI-preferred)
docker compose exec app composer test

# Run a specific test method
docker compose exec app vendor/bin/phpunit --filter=testCalculateAbv

# Run static analysis with specific path
docker compose exec app vendor/bin/phpstan analyse src/Domain/Cocktail

# View database schema
docker compose exec app sqlite3 ./storage/bar-assistant/database.ba3.sqlite ".schema"

# Query database
docker compose exec app sqlite3 ./storage/bar-assistant/database.ba3.sqlite "SELECT * FROM table_name LIMIT 10;"

Conventions

• All files must use strict typing
• Use named parameters in method calls for clarity: createCocktail(barId: $id, name: $name)
• Always specify parameter and return types
• Use generic type annotations in PHPDoc for arrays: @param CocktailIngredient[] $ingredients
• Use readonly for immutable DTOs and value objects
• Validate invariants in constructors and setter methods
• Write comments only to explain complex business logic
• New code should follow DDD and Hexagonal Architecture principles
• Tests will use Tests\Infrastructure\InMemory* implementations instead of mocks/stubs where applicable
• Changes in the src should only affect Unit testsuite
• Prefer static factory methods on aggregate roots with private constructors
• Do not write comprehensive documentation or reference guide in separate markdown files
• Since this is legacy code with already in place database schema the model identities are auto incrementing integers generated by a database and usually filled in by setId() method call

Architecture patterns (src folder - DDD/Hexagonal)

• Entities use private constructors with public static factory methods
• Aggregate roots are final classes implementing Identity interface
• Value objects are readonly with equals() method for comparison
• Application services use readonly DTOs for input/output
• Methods return $this for fluent chaining where appropriate
• Use InMemory* implementations for unit tests instead of mocks
• Use UbiquitousLanguage.md as a reference

Testing

• Write tests only when explicitly asked
• Unit tests for domain logic in tests/Unit
• Feature tests for HTTP endpoints in tests/Feature

CI pipeline (what runs in GitHub Actions)

1. composer install
2. ./vendor/bin/pint --test (code style check)
3. composer test (runs php artisan test — the Laravel test wrapper, not raw phpunit)
4. vendor/bin/phpstan analyse
5. Spectral API spec linting (docs/*.yaml)

Tools at Your Disposal

• phpstan - PHP Static Analysis Tool (level: max)
• pint - Laravel code style formatter
• phpunit - PHP test runner
• rector - Automated refactoring tool