Yisroel Baum
ff95e2d2ee
Update the AI guidance for the scaffolded npm application, its actual validation scripts, and its independent runtime boundary. Record the current lack of frontend test tooling without inventing commands.
108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# Backend context
|
|
|
|
Read `ai/shared.md` first. This file covers backend-specific rules.
|
|
|
|
## Project context
|
|
|
|
**Stack:** PHP 8.4, Laravel 13, PHPUnit, Larastan, Composer.
|
|
|
|
**Location:** `backend/`.
|
|
|
|
The application is still close to the Laravel starter structure. Do not
|
|
introduce a domain architecture, repository layer, service layer, or other
|
|
abstraction before the codebase and requested behavior justify it. Match
|
|
existing Laravel conventions and inspect similar code before adding a new
|
|
pattern.
|
|
|
|
## Laravel patterns
|
|
|
|
- Keep controllers thin. Put reusable business behavior in an appropriately
|
|
named application or domain class once the behavior warrants extraction.
|
|
- Use dedicated request validation rather than validating substantial payloads
|
|
inline in controllers.
|
|
- Let unexpected exceptions reach Laravel's exception handler. Catch only
|
|
exceptions that can be handled meaningfully at the current boundary.
|
|
- Use Eloquent relationships and query scopes consistently rather than
|
|
duplicating query fragments.
|
|
- Avoid speculative interfaces and abstractions with only one trivial
|
|
implementation.
|
|
- The Vue application is a separate project under `frontend/website/`.
|
|
- Keep frontend source, dependencies, builds, and delivery out of the backend
|
|
unless the user explicitly asks to integrate them.
|
|
- The backend root route is intentionally unclaimed. The built-in health
|
|
endpoint is `/up`.
|
|
|
|
## Tests
|
|
|
|
- Follow the existing PHPUnit organization under `tests/Unit/` and
|
|
`tests/Feature/`.
|
|
- Prefer `PHPUnit\Framework\TestCase` when a test only exercises plain PHP.
|
|
- Extend `Tests\TestCase` only when the test needs Laravel's container,
|
|
facades, database, routing, or HTTP kernel.
|
|
- HTTP feature tests extend `Tests\TestCase`.
|
|
- Use `RefreshDatabase` when a test reads or writes database state.
|
|
- Assert behavior at the appropriate seam:
|
|
- Unit tests cover isolated business behavior and edge cases.
|
|
- Feature tests cover routing, middleware, validation, persistence, and
|
|
response shape.
|
|
- Do not duplicate every business branch through the HTTP layer when unit
|
|
coverage already proves it. Feature tests should focus on wiring and the
|
|
public contract.
|
|
|
|
## Test database
|
|
|
|
- Development and runtime use PostgreSQL through the local Unix socket.
|
|
- PHPUnit intentionally uses SQLite `:memory:` as configured in
|
|
`phpunit.xml`.
|
|
- Feature tests are self-contained and do not require the process-compose
|
|
PostgreSQL service.
|
|
- Never point `RefreshDatabase` tests at the development PostgreSQL database.
|
|
- Keep mail set to the PHPUnit `array` transport unless a test explicitly
|
|
exercises a real mail integration.
|
|
|
|
## PHP rules
|
|
|
|
- Put imports at the top of the file. Do not use inline fully qualified class
|
|
names when a normal `use` statement is clearer.
|
|
- Do not use arrow functions. Use regular anonymous functions.
|
|
- Do not add default values to function or constructor parameters. Pass every
|
|
argument explicitly, including nullable arguments.
|
|
- Use descriptive names for classes, methods, parameters, and local
|
|
variables.
|
|
- Document exceptions with `@throws` when a caller is expected to handle
|
|
them.
|
|
|
|
## Seeders
|
|
|
|
- Keep `DatabaseSeeder` as the orchestrator.
|
|
- Split substantial seed data into one seeder per domain concept and invoke
|
|
them in dependency order.
|
|
- Do not add production repository or model APIs solely to make seeding
|
|
convenient.
|
|
- Use existing lookup methods for cross-seeder relationships. When a group of
|
|
records only makes sense together, keep them in one seeder and retain local
|
|
references.
|
|
|
|
## Migrations
|
|
|
|
- Attainly is not in production yet.
|
|
- While no production database exists, edit the original `create_*` migration
|
|
when changing a table instead of accumulating follow-up alter migrations.
|
|
- Keep one migration file per table during this pre-production phase.
|
|
- Rebuild the development database with:
|
|
|
|
```sh
|
|
php artisan migrate:fresh --seed
|
|
```
|
|
|
|
- Once a production database exists, replace this policy with additive,
|
|
forward-only migrations.
|
|
|
|
## Before completing backend work
|
|
|
|
- Run the focused test during development.
|
|
- Run `php artisan test` before completion.
|
|
- Run the Composer lint and static-analysis scripts when their dependencies
|
|
are available.
|
|
- Fix failures caused by the change. Report unrelated baseline failures
|
|
precisely rather than hiding them or expanding scope without authorization.
|