# NREMS Laravel Boilerplate Implementation Plan > **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Build the reusable NREMS Laravel 13 boilerplate: Theme A shell, Fortify auth (login/forgot/reset), Blade form-component library, and the Projects & Units module (5-table inventory), fully tested — then clone to a spatie/laravel-html variant repo. **Architecture:** Standard Laravel 13 skeleton (no module packages). Thin controllers → FormRequests → Eloquent/services; yajra DataTable classes for every list; spatie permission + policies with `can:` middleware (defense in depth); spatie activitylog on all models; Theme A static assets served from `public/assets` (no Vite build needed). Server is authoritative for all calculations; JS mirrors for UX only. **Tech Stack:** PHP 8.3 (WSL) · Laravel 13 (v13.26.x) · MySQL 8 (WSL, running) · laravel/fortify · spatie/laravel-permission · spatie/laravel-activitylog · yajra/laravel-datatables ^13 · proengsoft/laravel-jsvalidation · Pest · Pint · Larastan (level 6) · Metronic-based Theme A (Bootstrap 5, jQuery, select2 included in `plugins.bundle`). **Binding spec:** `docs/superpowers/specs/2026-08-23-nrems-boilerplate-design.md` — read it fully before any task. On any conflict, the spec wins; for view markup, Theme A HTML at `/home/vivek/nrems/nrems-themes/theme-a-wireframe/` wins. **Non-negotiable conventions (every task):** - TDD: failing test → minimal implementation → green → commit. Definition of done per task: `composer test` green AND `composer analyse` clean AND `composer lint` clean. - No raw SQL without bindings. `{{ }}` only in Blade (`{!! !!}` needs reviewer sign-off; the only pre-approved uses are `{!! JsValidator::formRequest(...) !!}` and yajra `{!! $dataTable->table() !!}` / `scripts()`). - Explicit `$fillable`, `casts()`, `SoftDeletes` + `LogsActivity` on all domain models. - All user-visible strings via `__('...')` with keys in `lang/en/*.php`. - Commit messages: conventional (`feat:`, `test:`, `chore:`…), each ending with `Co-Authored-By: Claude Fable 5 `. --- ## Chunk 1: Skeleton, packages, theme shell ### Task 1: Create the Laravel 13 project inside the existing repo **Files:** whole Laravel skeleton in `/home/vivek/nrems-app` (repo already contains `.git` + `docs/`). - [ ] **Step 1:** `composer create-project` refuses non-empty dirs — create in a sibling and merge: ```bash cd /home/vivek composer create-project laravel/laravel nrems-app-tmp "^13.0" --prefer-dist --no-interaction rsync -a --exclude .git nrems-app-tmp/ nrems-app/ rm -rf nrems-app-tmp cd nrems-app ``` - [ ] **Step 2:** Create DB + dedicated user (idempotent): ```bash sudo mysql -e "CREATE DATABASE IF NOT EXISTS nrems_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER IF NOT EXISTS 'nrems'@'localhost' IDENTIFIED BY 'nrems_local_dev'; GRANT ALL PRIVILEGES ON nrems_app.* TO 'nrems'@'localhost'; FLUSH PRIVILEGES;" ``` (Also create `nrems_app_test` the same way for the test suite; grant `nrems` on it too.) - [ ] **Step 3:** Configure `.env` and `.env.example` (example gets the same keys with placeholder secrets): `APP_NAME=NREMS`, `APP_URL=http://localhost:8000`, `DB_CONNECTION=mysql`, `DB_DATABASE=nrems_app`, `DB_USERNAME=nrems`, `DB_PASSWORD=nrems_local_dev`, `SESSION_DRIVER=database`, `MAIL_MAILER=log`, `SEED_ADMIN_EMAIL=admin@nrems.local`, `SEED_ADMIN_PASSWORD=` (blank in example). Point `phpunit.xml` at `nrems_app_test` (env `DB_DATABASE`); tests use `RefreshDatabase`. Do NOT use `:memory:` sqlite — we test against MySQL 8 like production. - [ ] **Step 4:** Verify: `php artisan migrate && php artisan about` → shows Laravel 13.x, MySQL. `php artisan serve` responds 200 on `/`. - [ ] **Step 5:** Commit: `chore: scaffold Laravel 13 skeleton with MySQL + session/database config` ### Task 2: Install packages + QA toolchain **Files:** `composer.json`, published configs under `config/`, `phpstan.neon`, `pint.json`, migrations from vendors. - [ ] **Step 1:** Production packages: ```bash composer require laravel/fortify spatie/laravel-permission spatie/laravel-activitylog "yajra/laravel-datatables:^13" proengsoft/laravel-jsvalidation ``` - [ ] **Step 2:** Dev packages + Pest init (create-project ships PHPUnit; convert): ```bash composer require --dev pestphp/pest pestphp/pest-plugin-laravel larastan/larastan laravel/pint --with-all-dependencies ./vendor/bin/pest --init # if it complains tests exist, follow its prompt; keep tests/Pest.php with RefreshDatabase bound to Feature tests ``` - [ ] **Step 3:** Vendor publishes + fortify install: ```bash php artisan fortify:install php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-migrations" php artisan vendor:publish --provider="Yajra\DataTables\DataTablesServiceProvider" php artisan vendor:publish --provider="Proengsoft\JsValidation\JsValidationServiceProvider" php artisan migrate ``` - [ ] **Step 4:** `phpstan.neon`: larastan extension, `level: 6`, `paths: [app]`. `pint.json`: `{"preset": "laravel"}`. Composer scripts: ```json "scripts": { "test": "@php artisan test", "analyse": "phpstan analyse --memory-limit=1G", "lint": "pint --test", "lint:fix": "pint" } ``` - [ ] **Step 5:** Verify all three commands pass on the fresh skeleton. Commit: `chore: install auth/permission/audit/datatables/jsvalidation + Pest/Larastan/Pint toolchain` ### Task 3: Theme A assets + app layout shell + error pages **Files:** - Copy: `/home/vivek/nrems/nrems-themes/theme-a-wireframe/assets/` → `public/assets/` (verbatim: `css/`, `js/`, `media/`, `plugins/`) - Create: `resources/views/layouts/app.blade.php`, `resources/views/layouts/guest.blade.php`, `resources/views/layouts/partials/sidebar.blade.php`, `topbar.blade.php`, `footer.blade.php` - Create: `resources/views/errors/403.blade.php`, `404.blade.php`, `500.blade.php`, `resources/views/layouts/error.blade.php` - Modify: `public/assets/css/theme-a.css` (append global responsive tab-nav rule) **Markup source:** `theme-a-wireframe/index.html` — its ``, body attributes (`id="kt_app_body"`, `data-*` attrs), early-init inline script, sidebar block (`kt_app_sidebar`), header (`kt_app_header`), and closing script tags (`plugins.bundle.js`, `scripts.bundle.js`, theme custom JS) must be transplanted **exactly**, replacing static hrefs with `{{ asset('assets/...') }}`, page content with `@yield('content')` / `{{ $slot }}`, page title with `@yield('title')`, and active-menu state with a `request()->routeIs()` helper. - [ ] **Step 1 (failing test):** `tests/Feature/Layout/AppShellTest.php` (Pest): an authenticated user GET `/dashboard` sees `id="kt_app_sidebar"`, `NREMS`, and `assets/css/theme-a.css`; a guest is redirected to `/login`. Also: GET a nonexistent URL as guest → 404 page contains `theme-a.css` (error layout). Expect failures (routes/views missing). - [ ] **Step 2:** Copy assets; build the four layout files + partials. Sidebar entries = the v12 sections (Main/Inventory/Sales/Operations/Document Uploads/Administration) but **only Dashboard is a live route now**; all others render with `href="#"` and a `disabled`-style class, each wrapped in `@can` checks where a permission exists (`projects.view`, `units.view`, `unit_types.view`) — unreachable modules stay visible-but-inert only for Super Admin (`hasRole('Super Admin')`), hidden otherwise. Note: `@can` on not-yet-seeded permissions is safe — spatie's gate returns false, entries just hide; the role check is likewise false for everyone until Task 9 seeds roles (the Step 1 test deliberately avoids asserting on gated entries). Guest layout = minimal centered card (used by auth pages, Task 8). Error layout = standalone (inline-link theme CSS only, **no session/auth calls**), and 403/404/500 views extend it. No registration needed — Laravel auto-discovers `resources/views/errors/`. - [ ] **Step 3:** Append to `theme-a.css` the global tab fix: ```css /* Global: tab navs never clip on small screens (spec §2) */ .nav-tabs, .nav-line-tabs { flex-wrap: nowrap; overflow-x: auto; overflow-y: hidden; scrollbar-width: thin; } .nav-tabs .nav-item, .nav-line-tabs .nav-item { white-space: nowrap; } ``` Also create `routes/dev.php`, loaded from `web.php` only when `app()->environment('local', 'testing')`: one route `GET /dev/tab-demo` (auth) rendering a page with a 7-item `nav-line-tabs` strip inside a card — the verification vehicle for this fix (no in-scope page has tabs; spec §2 requires the fix be *verified* this round). Task 22's responsive smoke screenshots this page at 390px and asserts no clipping. - [ ] **Step 4:** Temporary `/dashboard` route (real one in Task 6) rendering `layouts/app` with empty content so the test can pass. Run tests → green. `composer analyse && composer lint`. - [ ] **Step 5:** Commit: `feat: Theme A layout shell, guest/error layouts, responsive tab fix` ### Task 4: Base conventions — HasAudit trait, helpers, config, security headers **Files:** - Create: `app/Models/Concerns/HasAudit.php`, `app/Support/helpers.php`, `config/nrems.php`, `app/Http/Middleware/SecurityHeaders.php` - Modify: `composer.json` (autoload files), `bootstrap/app.php` (append middleware) - Test: `tests/Unit/Support/FormatInrTest.php`, `tests/Feature/Http/SecurityHeadersTest.php` - [ ] **Step 1 (failing tests):** `format_inr(12345678.5)` → `₹1,23,45,678.50`; `format_inr(0)` → `₹0.00`; negative → `-₹1,000.00`. Security headers: any response carries `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`. - [ ] **Step 2:** Implement: ```php // app/Support/helpers.php if (! function_exists('format_inr')) { function format_inr(float|int|string $amount, int $decimals = 2): string { $amount = round((float) $amount, $decimals); $negative = $amount < 0; [$int, $frac] = array_pad(explode('.', number_format(abs($amount), $decimals, '.', '')), 2, ''); if (strlen($int) > 3) { $last3 = substr($int, -3); $rest = substr($int, 0, -3); $int = preg_replace('/\B(?=(\d{2})+(?!\d))/', ',', $rest).','.$last3; } return ($negative ? '-' : '').'₹'.$int.($decimals > 0 ? '.'.$frac : ''); } } ``` `HasAudit` trait: `use SoftDeletes, LogsActivity;` + `getActivitylogOptions(): LogOptions` → `LogOptions::defaults()->logFillable()->logOnlyDirty()->dontSubmitEmptyLogs()`. `config/nrems.php`: `['date_format' => 'd-m-Y', 'per_page' => 25]`. Middleware sets the three headers; append globally in `bootstrap/app.php` `->withMiddleware(fn ($m) => $m->append(SecurityHeaders::class))`. - [ ] **Step 3:** Green + analyse + lint. Commit: `feat: audit trait, INR formatter, security headers, nrems config` ### Task 5: Reusable UI components — breadcrumbs, status badge, card **Files:** - Create: `resources/views/components/breadcrumbs.blade.php`, `components/status-badge.blade.php`, `components/card.blade.php`, `app/View/Components/StatusBadge.php` - Test: `tests/Feature/Components/UiComponentsTest.php` Markup: Theme A uses its own badge scheme — `` etc., styled at `theme-a.css:~1597` (NOT Bootstrap `badge badge-light-*`). **Decision: adopt `nrems-badge ` (HTML wins).** `theme-a.css` currently styles only `available|booked|sold|blocked` + payment/doc statuses; append styles for the missing enum statuses `held|registered|possessed|management_quota` (colors: held=amber, registered=teal, possessed=dark gray, management_quota=purple — consistent with the existing palette), plus a neutral `.nrems-badge.unknown`. `StatusBadge` maps status string → that class; unknown status → `unknown` (never throws). No `sold` mapping (spec: enum only). Breadcrumb markup: Theme A uses a plain `d-flex` div marked `` (see `project-management.html` ~line 384) — copy that, not Bootstrap `.breadcrumb`. - [ ] **Step 1 (failing test):** `Blade::render('')` contains `nrems-badge available` and `Available`; unknown status renders `nrems-badge unknown`. Breadcrumbs component renders home link + items. Card renders title slot + body. - [ ] **Step 2:** Implement, labels via `__('nrems.status.available')` etc. in `lang/en/nrems.php`. - [ ] **Step 3:** Green + analyse + lint. Commit: `feat: breadcrumbs, status-badge, card components` ### Task 6: Dashboard (static shell) + named route **Files:** `resources/views/dashboard.blade.php`, `app/Http/Controllers/DashboardController.php` (invokable), `routes/web.php`, test `tests/Feature/DashboardTest.php`. - [ ] **Step 1 (failing test):** guest → redirect `/login`; authenticated user → 200, sees `Dashboard` heading and stat-card markup. - [ ] **Step 2:** Port `index.html` content region into `dashboard.blade.php` (static placeholder stats per spec §7 — keep the wireframe's dummy numbers, mark section with `{{-- placeholder: real widgets ship with later modules --}}`). Route: `Route::middleware('auth')->get('/dashboard', DashboardController::class)->name('dashboard');` `/` redirects to `/dashboard`. Remove Task 3's temporary route. - [ ] **Step 3:** Green + analyse + lint. Commit: `feat: dashboard shell page` --- ## Chunk 2: Auth module ### Task 7: Fortify backend — login/logout/reset flows **Files:** - Modify: `config/fortify.php` (features: only `Features::resetPasswords()`; `views => true`; `home => '/dashboard'`), `app/Providers/FortifyServiceProvider.php` (created by fortify:install), `app/Providers/AppServiceProvider.php` - Test: `tests/Feature/Auth/LoginTest.php`, `tests/Feature/Auth/PasswordResetTest.php` - [ ] **Step 1 (failing tests, write ALL first):** - login ok → redirect `/dashboard`, session regenerated (assert `Auth::check()`) - wrong password → back with generic error, no user enumeration (same message for unknown email — assert identical error string for both cases) - throttle: 6th rapid attempt for same email+IP → 429 or throttle error message - logout → session invalidated, guest again - forgot-password with known email → reset link "sent" (Notification::fake, assert `ResetPassword` notification) - forgot-password with unknown email → **same generic success response** (no enumeration) - reset with valid token → password updated (assert new password logs in), old sessions still valid is NOT required - reset with invalid/expired token → error, password unchanged - weak password (7 chars) rejected on reset - [ ] **Step 2:** Configure. In `FortifyServiceProvider::boot`: view bindings (`Fortify::loginView`, `requestPasswordResetLinkView`, `resetPasswordView` → the Task 8 views), keep Fortify's default `login` RateLimiter (5/min by email+IP). In `AppServiceProvider::boot`, gate the HaveIBeenPwned check to production so the test suite never touches the network: ```php Password::defaults(function () { $rule = Password::min(8)->letters()->mixedCase()->numbers(); return app()->isProduction() ? $rule->uncompromised() : $rule; }); ``` Fortify's reset rules use `Password::defaults()` by default in current versions; verify. - [ ] **Step 3:** Green + analyse + lint. Commit: `feat: Fortify auth backend (login, logout, password reset) with throttle + strong passwords` ### Task 8: Auth pages — Metronic stock restyled to Theme A **Files:** `resources/views/auth/login.blade.php`, `auth/forgot-password.blade.php`, `auth/reset-password.blade.php` (extend `layouts/guest`). Theme A has NO auth HTML (spec §6). Build a single centered-card auth layout: white card on `bg-light`, NREMS logo (`assets/media/logos/nrems-icon.svg`), Inter font, primary `#2563EB` buttons (`btn-primary` already themed by `theme-a.css`). Fields use plain Bootstrap markup for now (form components arrive in Chunk 3 — do NOT block auth on them; Task 13 retrofits). - [ ] **Step 1 (failing test, in `tests/Feature/Auth/AuthPagesTest.php` — Task 13 extends this same file):** GET `/login`, `/forgot-password`, and a reset-password URL (valid token) each return 200 and contain the form actions + CSRF token. (View-render smoke; flows already covered by Task 7.) - [ ] **Step 2:** Build the three views: email/password inputs, "Forgot password?" link, session status flash (`session('status')`) on forgot page, validation errors inline (`@error`). Escape everything. - [ ] **Step 3:** Green + analyse + lint. Manual: `php artisan serve`, visually confirm at 390/768/1280 px. Commit: `feat: themed auth pages (login, forgot, reset)` ### Task 9: Roles, permissions, seeded Super Admin **Files:** - Create: `database/seeders/RolePermissionSeeder.php`, `database/seeders/AdminUserSeeder.php`; Modify: `DatabaseSeeder.php`, `AppServiceProvider.php` (Gate::before) - Test: `tests/Feature/Auth/RolePermissionSeedTest.php` Matrix (spec §5): `projects|units|unit_types` × `view|create|edit|delete` = 12 permissions. Roles: `Super Admin` (no direct perms; `Gate::before` returns true for it), `Admin` (all 12), `Sales` (`projects.view`, `units.view`), `Operations` (`projects.view`, `units.*`, `unit_types.view`). - [ ] **Step 1 (failing test):** after seeding — 12 permissions exist; role→permission counts as above; Super Admin user exists with `SEED_ADMIN_EMAIL`; `$superAdmin->can('projects.delete')` true via Gate::before; a Sales user `->can('projects.delete')` false. - [ ] **Step 2:** Implement seeders (idempotent: `firstOrCreate` everywhere). AdminUserSeeder: read via config, not `env()` (cached config in production makes `env()` return null): add `'seed_admin_email' => env('SEED_ADMIN_EMAIL', 'admin@nrems.local'), 'seed_admin_password' => env('SEED_ADMIN_PASSWORD')` to `config/nrems.php` and read `config('nrems.seed_admin_password')`, falling back to `'password'` ONLY when `app()->environment('local', 'testing')`, otherwise `throw new RuntimeException('SEED_ADMIN_PASSWORD required')`. `Gate::before(fn ($user) => $user->hasRole('Super Admin') ? true : null);` User model gets `HasRoles`. - [ ] **Step 3:** Green + analyse + lint. Commit: `feat: role/permission matrix + seeded Super Admin` ### Task 10: Auth activity log **Files:** `app/Listeners/LogAuthenticationActivity.php`, wire in `AppServiceProvider` (or `EventServiceProvider` pattern for L13: `Event::listen`). Test: `tests/Feature/Auth/AuthActivityLogTest.php`. - [ ] **Step 1 (failing test):** successful login writes `activity_log` row (`log_name=auth`, description `login`, causer = user); logout writes `logout`; failed attempt writes `login_failed` with attempted email in properties (NOT the password). - [ ] **Step 2:** Listen to `Illuminate\Auth\Events\{Login,Logout,Failed}`; use `activity('auth')->...->log(...)`. Assert no password ever stored (test greps properties json). - [ ] **Step 3:** Green + analyse + lint. Commit: `feat: audit trail for auth events` --- ## Chunk 3: Form component library + jsvalidation ### Task 11: Blade form components **Files:** - Create: `resources/views/components/form/input.blade.php`, `form/textarea.blade.php`, `form/select.blade.php`, `form/select2.blade.php`, `form/date.blade.php`, `form/checkbox-group.blade.php`, `form/submit.blade.php`, `form/group.blade.php` (label + error wrapper used by all) - Test: `tests/Feature/Components/FormComponentsTest.php` API contract (documented in `docs/adding-a-module.md`, Task 22): every field component accepts `name`, `label`, `:value` (old-input aware via `old($name, $value)`), `required` (renders the Theme A red asterisk `*`), arbitrary attrs pass through `{{ $attributes }}`. Error state: `@error($name)` adds `is-invalid` + `
`. `select`/`select2` accept `:options` (assoc array value=>label) + `placeholder`; `select2` adds `data-control="select2"` + `data-placeholder` (Metronic auto-inits select2 on that attribute — verify in `plugins.bundle.js`; if not auto-init, create `resources/views/layouts/partials/scripts.blade.php` NOW with one delegated init and include it from the app layout — Task 12 otherwise creates that file; whichever task needs it first creates it). `date` renders `type="date"` storing `Y-m-d`, displaying native picker (wireframe uses native date inputs). Markup classes copied from `add-project.html` field blocks (`form-label`, `form-control form-control-solid`, `form-select form-select-solid`). - [ ] **Step 1 (failing tests):** render each component via `Blade::render()`; assert: label + asterisk when required; `name`/`id` attributes; old input wins over `:value` (simulate `session()->flashInput()`); error class + message when errors bag has the key (including dot-to-bracket conversion: name `amenities[]` / `wings.0.name` error keys resolve); select marks `selected` correctly incl. `0`-value options; checkbox-group renders checked states from array old input. - [ ] **Step 2:** Implement. Keep components dumb — no DB, no auth. `form/group.blade.php` is the shared shell; field components compose it. - [ ] **Step 3:** Green + analyse + lint. Commit: `feat: themed Blade form component library` ### Task 12: DataTable wrapper + modal component **Files:** `resources/views/components/datatable.blade.php`, `components/modal.blade.php`; test `tests/Feature/Components/DatatableModalTest.php`. `x-datatable` wraps yajra's html-builder output region: renders `{!! $dataTable->table(['class' => 'table align-middle table-row-dashed fs-6 gy-4'], true) !!}` inside the Theme A card + toolbar slot (search box/filters slot + "Add" button slot gated by `@can`). `x-modal` copies the modal pattern from `inquiry.html` (spec: only modal reference) — props: `id`, `title`, footer slot. - [ ] **Step 1 (failing test):** modal renders `modal fade`, id, title, slot content. Datatable component renders card wrapper + slots (pass a fake table string). - [ ] **Step 2:** Implement. Also create `resources/views/layouts/partials/scripts.blade.php` **if Task 11 didn't already** — its final content is the `@stack('scripts')` include plus any select2 delegated init from Task 11; add `@stack('styles')` in the layout head — layouts include both. - [ ] **Step 3:** Green + analyse + lint. Commit: `feat: datatable card wrapper + modal component` ### Task 13: jsvalidation integration + retrofit auth forms **Files:** Modify `resources/views/auth/*.blade.php`, create `resources/views/components/form/jsvalidation.blade.php` helper include; test additions in `tests/Feature/Auth/AuthPagesTest.php`. - [ ] **Step 1 (failing test):** `/login` page HTML includes `jsvalidation.js` script and a generated validation script block. - [ ] **Step 2:** Publish check: `public/vendor/jsvalidation/js/jsvalidation.js` exists (from Task 2 publish). Create `app/Http/Requests/Auth/LoginPageRequest.php` mirroring Fortify's login rules (email required|email, password required) — used ONLY to drive jsvalidation on the page: `{!! JsValidator::formRequest(App\Http\Requests\Auth\LoginPageRequest::class, '#kt_login_form') !!}`. Same for forgot/reset pages. Rebuild the three auth forms with `x-form.*` components (Chunk 3 now exists). - [ ] **Step 3:** Green + analyse + lint. Manual browser check: submitting empty login shows client-side errors without a request. Commit: `feat: client-side validation via jsvalidation + auth forms on component library` --- ## Chunk 4: Projects & Units module, seeds, docs, variant repo ### Task 14: Inventory schema — migrations, models, factories **Files:** - Create migrations (one file each, this order): `create_projects_table`, `create_project_wings_table`, `create_floor_plans_table`, `create_unit_types_table`, `create_units_table` - Create: `app/Models/{Project,ProjectWing,FloorPlan,UnitType,Unit}.php`, enums `app/Enums/{ProjectStatus,ProjectType,WingType,UnitCategory,FloorType,UnitStatus,Facing}.php` (string-backed), factories for all five - Test: `tests/Feature/Models/InventorySchemaTest.php` Schema (columns per spec §7 + architecture doc; all tables `id`, timestamps, softDeletes unless noted): - `projects`: name, code unique, project_type (string ← `ProjectType`), status (string ← `ProjectStatus` — **enum cases must be generated from the exact `