` 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. Keep a way to run the whole suite against each real server, and put anything driver-sensitive in its own test directory — those tests must **not** branch on the driver, because the point is that the engines agree. **⚠ The divergences that bite, all found the hard way:** - **Searching:** use `whereLike()` / `orWhereLike()`, never `where(..., 'like', ...)`. MySQL's `utf8mb4_unicode_ci` makes `LIKE` case-insensitive and PostgreSQL's is case-sensitive, so a raw `like` silently behaves differently. Laravel compiles `whereLike()` to `ILIKE` on PostgreSQL. - **NULL ordering:** `ORDER BY col ASC` puts NULLs first on MySQL and last on PostgreSQL. Order explicitly — `(col IS NULL) DESC, col ASC`. `NULLS FIRST` is PostgreSQL-only and forces a fork. - **`CASE` ladders always need an `ELSE`.** Without one an unmatched row sorts as NULL, and the two drivers disagree about where that goes. - **Never aggregate a boolean.** `SUM(bool)` works on MySQL and raises on PostgreSQL. Use `SUM(CASE WHEN cond THEN 1 ELSE 0 END)`. - **Division:** `COUNT(*) / 7` is integer division on PostgreSQL and decimal on MySQL. Divide in PHP, or divide by a float. - **Elapsed time:** measure seconds and divide. `TIMESTAMPDIFF(HOUR, …)` truncates where `EXTRACT(EPOCH …)/3600` does not, and MySQL's `DATEDIFF` counts date boundaries where PostgreSQL's `DATE_PART` counts elapsed interval. - **Week numbers:** PostgreSQL's `EXTRACT(WEEK)` is ISO-8601; MySQL's `WEEK()` needs mode 3 to match. - **`TO_CHAR` pads:** use `FM` (`FMMon`) when the output is compared or grouped. - **Aliases in `HAVING`:** PostgreSQL allows a select alias in `GROUP BY` and `ORDER BY` but not `HAVING`. Repeat the aggregate there. - **`->first()` needs an `orderBy`** when the query can match more than one row; the engines do not agree on which row comes back otherwise. - **New columns:** no new `->enum(` (use `->string()` plus `Rule::in()`), no new `->json(` (use `->jsonb()`), and no `->after(`, which PostgreSQL ignores. Worth a test that fails the build if those counts rise. - **Identifier length:** truncated at 63 characters by PostgreSQL and 64 by MySQL. Name long constraints explicitly rather than letting a generated name grow past the limit. ## 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 Tradixor is a cloud-based, multi-tenant SaaS platform built for importers, distributors, and retailers who manage goods across international and local supply chains. The platform unifies the complete product lifecycle — from sourcing trips abroad, through international shipping and customs clearance, local purchase and production, into warehoused inventory, and finally to point-of-sale transactions with integrated finance and accounting. The platform is domain-agnostic by design. TradiXor provides automation tools and real-time insights that empower organizations to make smarter, data-driven decisions. ## Module folders Detected under `app/Models`. The same names should run through `app/Http/Controllers`, `app/Services`, `app/Policies`, `resources/js/pages` and `tests/Feature`. | Folder | Holds | | --- | --- | | `Api` | | | `Concerns` | | | `Finance` | | | `Hr` | | | `Inventory` | | | `LocalProcurement` | | | `Logistics` | | | `Procurement` | | | `Production` | | | `Sales` | | | `Security` | | | `System` | | | `Traits` | | ## Shared components to reach for | Need | Component | | --- | --- | | A table of records | `components/datatables/DataTable.vue`, `ServerPaginatedDataTable.vue` | | A searchable dropdown | `components/ui/SearchableSelect.vue` | | A phone or telephone field | `components/ui/phone-input/index.vue` | | A chart | `components/charts/` — `BarChart`, `LineChart`, `PieChart`, `DoughnutChart` | | A checkbox | native `` with the checkbox class in `app.css` | | A busy state for a button that sends a request without a form | `composables/useBusyAction.ts` — `busy.run(key, (visit) => router.put(…, visit))` with `:loading="busy.is(key)"`; `busy.track(key, …)` for axios/fetch | | A table row action that sends a request | take `(row, visit)` and pass `visit` to the router call (`mergeVisit` when it has options of its own); the table spins that row's actions button | ## How far the lean-controller rule has actually got **70 Form Request class(es) against 120 controllers, and 36 service class(es).** Treat the rule as guidance for new work until those numbers say otherwise. ## Running it locally and running the suite Database `tradixorclean` on port 5432. **⚠ Point the suite at a SEPARATE database** — `RefreshDatabase` runs `migrate:fresh` and will destroy this one. 55 test files. ## Tools installed but switched off --- === boost rules === # Laravel Boost ## Artisan - Run Artisan commands directly via the command line (e.g., `php artisan route:list`). Use `php artisan list` to discover available commands and `php artisan [command] --help` to check parameters. - Inspect routes with `php artisan route:list`. Filter with: `--method=GET`, `--name=users`, `--path=api`, `--except-vendor`, `--only-vendor`. - Read configuration values using dot notation: `php artisan config:show app.name`, `php artisan config:show database.default`. Or read config files directly from the `config/` directory. - To check environment variables, read the `.env` file directly. ## Tinker - Execute PHP in app context for debugging and testing code. Do not create models without user approval, prefer tests with factories instead. Prefer existing Artisan commands over custom tinker code. - Always use single quotes to prevent shell expansion: `php artisan tinker --execute 'Your::code();'` - Double quotes for PHP strings inside: `php artisan tinker --execute 'User::where("active", true)->count();'` === php rules === # PHP - Always use curly braces for control structures, even for single-line bodies. - Use PHP 8 constructor property promotion: `public function __construct(public GitHub $github) { }`. Do not leave empty zero-parameter `__construct()` methods unless the constructor is private. - Use explicit return type declarations and type hints for all method parameters: `function isAccessible(User $user, ?string $path = null): bool` - Use TitleCase for Enum keys: `FavoritePerson`, `BestLake`, `Monthly`. - Prefer PHPDoc blocks over inline comments. Only add inline comments for exceptionally complex logic. - Use array shape type definitions in PHPDoc blocks. === deployments rules === # Deployment - Laravel can be deployed using [Laravel Cloud](https://cloud.laravel.com/), which is the fastest way to deploy and scale production Laravel applications. === tests rules === # Test Enforcement - Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass. - Run the minimum number of tests needed to ensure code quality and speed. Use `php artisan test --compact` with a specific filename or filter. === inertia-laravel/core rules === # Inertia - Inertia creates fully client-side rendered SPAs without modern SPA complexity, leveraging existing server-side patterns. - Components live in `resources/js/pages` (unless specified in `vite.config.js`). Use `Inertia::render()` for server-side routing instead of Blade views. - ALWAYS use `search-docs` tool for version-specific Inertia documentation and updated code examples. - IMPORTANT: Activate `inertia-vue-development` when working with Inertia Vue client-side patterns. # Inertia v3 - Use all Inertia features from v1, v2, and v3. Check the documentation before making changes to ensure the correct approach. - New v3 features: standalone HTTP requests (`useHttp` hook), optimistic updates with automatic rollback, layout props (`useLayoutProps` hook), instant visits, simplified SSR via `@inertiajs/vite` plugin, custom exception handling for error pages. - Carried over from v2: deferred props, infinite scroll, merging props, polling, prefetching, once props, flash data. - When using deferred props, add an empty state with a pulsing or animated skeleton. - Axios has been removed. Use the built-in XHR client with interceptors, or install Axios separately if needed. - `Inertia::lazy()` / `LazyProp` has been removed. Use `Inertia::optional()` instead. - Prop types (`Inertia::optional()`, `Inertia::defer()`, `Inertia::merge()`) work inside nested arrays with dot-notation paths. - SSR works automatically in Vite dev mode with `@inertiajs/vite` - no separate Node.js server needed during development. - Event renames: `invalid` is now `httpException`, `exception` is now `networkError`. - `router.cancel()` replaced by `router.cancelAll()`. - The `future` configuration namespace has been removed - all v2 future options are now always enabled. === laravel/core rules === # Do Things the Laravel Way - Use `php artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using `php artisan list` and check their parameters with `php artisan [command] --help`. - If you're creating a generic PHP class, use `php artisan make:class`. - Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior. ### Model Creation - When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `php artisan make:model --help` to check the available options. ## APIs & Eloquent Resources - For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention. ## URL Generation - When generating links to other pages, prefer named routes and the `route()` function. ## Testing - When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model. - Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`. - When creating tests, make use of `php artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests. ## Vite Error - If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `npm run build` or ask the user to run `npm run dev` or `composer run dev`. === wayfinder/core rules === # Laravel Wayfinder Use Wayfinder to generate TypeScript functions for Laravel routes. Import from `@/actions/` (controllers) or `@/routes/` (named routes). === pint/core rules === # Laravel Pint Code Formatter - If you have modified any PHP files, you must run `vendor/bin/pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style. - Do not run `vendor/bin/pint --test --format agent`, simply run `vendor/bin/pint --format agent` to fix any formatting issues. === phpunit/core rules === # PHPUnit - This application uses PHPUnit for testing. All tests must be written as PHPUnit classes. Use `php artisan make:test --phpunit {name}` to create a new test. - If you see a test using "Pest", convert it to PHPUnit. - Every time a test has been updated, run that singular test. - When the tests relating to your feature are passing, ask the user if they would like to also run the entire test suite to make sure everything is still passing. - Tests should cover all happy paths, failure paths, and edge cases. - You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files; these are core to the application. ## Running Tests - Run the minimal number of tests, using an appropriate filter, before finalizing. - To run all tests: `php artisan test --compact`. - To run all tests in a file: `php artisan test --compact tests/Feature/ExampleTest.php`. - To filter on a particular test name: `php artisan test --compact --filter=testName` (recommended after making a change to a related file). === inertia-vue/core rules === # Inertia + Vue Vue components must have a single root element. - IMPORTANT: Activate `inertia-vue-development` when working with Inertia Vue client-side patterns.