` is not reachable by keyboard and is announced as nothing. **If the project ships a user manual, editing a screen means editing its chapter.** Keep a test that holds the manual against the application — the routes it prints must answer, the menu entries it names must exist — because nothing else ties a chapter to the screen it describes, and documentation drifts silently by nature. ## Every screen is a phone screen too **Every rule here fails silently on a desktop and breaks the screen on a phone.** That asymmetry is why they are written down, and why they are worth a test that reads source. **Target 360px and up.** Check 360, 390 and 768 in device mode — 768 because that is where a `md:`-style breakpoint and any JavaScript media query meet, and they must not both be true at once. - **A dialog sets its width from `sm:` upward, never unprefixed and never with `!`.** The base carries a mobile cap (`w-full max-w-[calc(100%-2rem)] … sm:max-w-lg`), and because the class merge is `tailwind-merge`, a call site's own `max-w-*` **replaces** it. Worse, an unprefixed width and the base `sm:` width are different merge keys, so the override never removes the `sm:` one and loses on source order — the width appears to do nothing on desktop, someone reaches for `!`, and now it is broken at both ends. `sm:max-w-4xl` gives the same desktop result and keeps the guard. Anything wider than `lg` needs an `md:`/`lg:` step too, or a 640px viewport gets a 1000px layout. - **Heights use `dvh`, never `vh` and never `max-h-screen`.** `vh` on mobile is the URL-bar-hidden height. A full-height box centred with `translate-y-[-50%]` puts its own title above the screen, unreachable, because the scrolling happens inside the box. - **A form control is `text-base md:text-sm`, never `text-sm` alone.** Safari zooms the whole page when a focused control is under 16px and does not zoom back. The base components do this already; the failure is a call site overriding it. - **Touch sizing goes through `pointer-coarse:`, not a breakpoint.** A finger needs ~44px and a mouse does not, and `pointer-coarse` keys off the input device rather than the width — so touch gets a real target and no desktop screen moves a pixel. Set it once in the button variants. ⚠ It cannot be checked in device emulation, which emulates width and not pointer type. - **A `flex-1` item needs `min-w-0`.** A flex item's default `min-width: auto` refuses to shrink below its content's intrinsic width, so one wide table widens the row past the viewport and the whole document scrolls sideways. ⚠ Before deleting a width that looks like debris on a page container, check it is not the only thing clamping that minimum. - **A horizontally scrolling row is `justify-start`, never centred.** A centred flex container whose content overflows puts its first item at a negative offset, and `scrollLeft` cannot go negative — so the start becomes unreachable. Applies to tab strips, filter chips, any pill row. Give the row `max-w-full overflow-x-auto` and the items `shrink-0`. - **An overlay needs a way out that works without a keyboard.** A phone has no Escape key, so a sheet that hides its close button *and* disables outside dismissal cannot be closed at all — and it looks fine on a desktop, where Escape still works. That is exactly how it ships. - **Grids start at one column.** `sm:grid-cols-2` is right; a bare `grid-cols-3` is three columns on a phone. A tab strip given a column count starts at two. - **`title=""` is invisible on touch.** If it carries information that appears nowhere else, it is not documented. **Judgement matters more than the grep.** Distinguish unusable from merely tight: a two-column grid of label/value pairs is snug and fine, a two-column grid of input fields is not. An audit that reports everything is as useless as one that reports nothing. ## Guard tests that read source When breaking a rule produces no symptom on the machine the developer is using and a broken screen on the machine the user is using, **assert it by scanning source**. Most of the mobile and dialog rules above are enforced this way. Three things make the difference between a guard and a decoration: - **Prove it fails against the unfixed code before believing it.** Stash the fix, run the test, confirm it fails, restore. A guard that passes for the wrong reason is worse than none. - **Mutation-test the important ones.** Re-break one instance deliberately and confirm the guard fires and names the right file. - **⚠ Parse elements, not lines.** A formatter wraps long attribute lists, so a tag and its `class` routinely sit on different lines. A line-based scan silently skips exactly the worst offenders and then reports a clean run. **Say what they are.** They catch regressions; they did not catch the original bug and could not. Nothing here drives a browser, so layout is verified by looking at it. ## Migrations are consolidated, not accumulated **One migration per module, holding that module's tables in their settled form.** Every `ALTER`-style migration is folded back into the `Schema::create` it belongs to, and every table sits in the module that owns it. **So a new column goes into the create migration, not into a new file.** The schema is read as a definition rather than as a history; the history is in git, where it belongs. **Cross-cutting migrations stay separate and must run last**, because they run against every table: the CHECK constraints in one registry, any triggers, row-level security policies, and every foreign key after every table exists. Name them so they sort last. **⚠ ORDER MATTERS AND IS EASY TO GET WRONG.** A create migration must sort *before* the constraint registry, or its CHECK constraints are silently skipped — the registry walks its list and passes over any table that does not exist yet, so the constraint never appears and nothing fails. A consolidation once dropped seven CHECK constraints exactly that way, and the only thing that caught it was the schema fingerprint. **A schema fingerprint is how you prove a schema change was the one you meant.** Dump every column, comment, constraint and index in a stable order; run it before a structural refactor, run `migrate:fresh` on a scratch database afterwards, and diff. An empty diff is the only evidence worth having — folding migrations by hand is exactly where a column quietly becomes nullable, a default moves, or an index is not recreated, and none of those break a test. They break a deployment months later on a table nobody was looking at. **Comments are part of the schema, not documentation about it.** If generated documents read table and column comments, a fold that drops one silently empties a row of a deliverable. Note that `->change()` DROPS a column comment on PostgreSQL. ## Database conventions Write database-agnostic queries and portable schemas. Treat the primary database as the source of truth and make the other paths explicit. - Default to the query builder and Eloquent so the driver handles dialect differences. - Prefer portable column types (`string`, `text`, `json`, `timestamp`); avoid database-specific types unless guarded by a driver check. - Where a query genuinely differs — JSON operators, full-text search, `ILIKE` vs `LIKE`, date functions, `RETURNING` — branch on `DB::connection()->getDriverName()`. - Performance-critical paths may use database-specific features where the portable builder is too slow, but both drivers must be handled explicitly. **⚠ MariaDB reports itself as `'mysql'`, and it is not MySQL.** So `getDriverName() === 'mysql'` is necessary and *not sufficient* wherever the two diverge. Tell them apart by the server banner: ```php str_contains(strtolower(DB::selectOne('SELECT VERSION() AS v')->v), 'mariadb') ``` The known divergences, all found the hard way: - **Dropping a CHECK:** MySQL wants `DROP CHECK ` (8.0.16+) and has **no `IF EXISTS`** for it at any version. MariaDB wants `DROP CONSTRAINT IF EXISTS ` (10.2+) and does not accept `DROP CHECK`. `DROP CHECK IF EXISTS` is valid on neither — and a project emitted exactly that for months, because it only ever ran on PostgreSQL so nothing caught it. - **Dropping a foreign key:** MySQL wants `DROP FOREIGN KEY `, again with no `IF EXISTS`. MariaDB accepts `DROP FOREIGN KEY IF EXISTS` (10.1+). - Where the engine will not accept `IF EXISTS`, ask `information_schema.TABLE_CONSTRAINTS` first rather than dropping blind. **Run a fresh `migrate` against every engine you claim to support before believing a migration is portable.** A suite that runs on SQLite and the primary database touches neither MySQL nor MariaDB, so a migration can be green in CI and fail on the first deploy. ## Running the test suite - **A green run on SQLite has not tested what the database enforces.** SQLite installs no CHECK constraints, no triggers and no row-level security, so the tests that prove those guarantees skip — and, worse, tests that *do not* skip can pass there for the wrong reason. Two live 500s once sat green on SQLite for months, both writing a string a CHECK constraint did not permit. **Any change that writes a constrained string column — a status, a channel, a type, a scope — must be exercised on the real database.** - **Point the suite at a separate database.** `RefreshDatabase` runs `migrate:fresh` and will otherwise destroy development data. Override the connection on the command line rather than editing `phpunit.xml`. - **Never run two suites against the same test database at once**, and never edit files while a run is in progress — the result describes a tree that no longer exists. - **Prove a new test fails against the old code before believing it.** - **`php artisan test` can die partway through, print no summary, and still exit 0** — so a CI step checking the exit code sees a pass for a run that never finished. It is a memory ceiling, not a broken test, and it returns as the suite grows. Use `php -d memory_limit=2G vendor/bin/phpunit` for the whole suite and keep `php artisan test --compact --filter=…` for single files. - **A front end with a build step needs building before the suite runs on a fresh clone**, or every test that renders a full page fails with a manifest error that reads like an application bug. ## Docker: running and deploying The patterns worth keeping whatever the project: - **Development and production are separate down to the compose project name**, so nothing in one can reach a container, volume or database belonging to the other. - **The production image is the artefact.** Dependencies, built assets and source are layers, not mounts, so what runs is what was built and a deployment is a new container rather than a file copy. Opcache with `validate_timestamps = 0` depends on that being true. - **There is no dev-server service in production**, so the browser can never be told to fetch assets from a machine that is not there. Removing the service is the only way to make that impossible. - **Guard the production build on the settings that fail silently at run time** — an empty app key, an empty database password, a non-production environment (which may seed demo data with published logins), and debug left on. Refuse to build rather than discover it later. - **`optimize` runs at container start, not at build**, because config caching freezes what `env()` returns and those values arrive at run time. One consequence: `env()` outside `config/` returns null once cached, so anything reading `env()` directly breaks under a cached config. - **A backup takes both halves** — the database and the file storage. The database knows which file belongs to which record; the volume holds the file. Either alone restores to rows pointing at documents that do not exist. - **Environment files are read twice**, by the framework and by compose, so the database name, user and password provision the container *and* configure the connection to it. They cannot drift, and changing them only takes effect on a volume that does not exist yet. # This project ## What it is ## Platform and delivery ## Module folders ## Tenancy and authorisation ## Domain rules that are not obvious from the schema ## Shared components to reach for | Need | Component | | --- | --- | | | | ## How far the conventions have actually got ## Running it locally ## Deploying ## Running the suite here ## Tools installed but switched off ## Documentation and where the plan lives