TenantAtlas/specs/182-platform-relocation/plan.md

# Implementation Plan: Platform Relocation to apps/platform

**Branch**: `182-platform-relocation` | **Date**: 2026-04-07 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/182-platform-relocation/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/182-platform-relocation/spec.md`

## Summary

Relocate the entire Laravel platform application into `apps/platform` while turning the repo root into a true orchestration and metadata layer. The implementation keeps the app whole instead of splitting Composer, Vite, PHPUnit, Filament, Tailwind, or bootstrap files across root and app, so existing internal relative paths stay stable once moved. The main technical work is therefore at the boundaries: root `docker-compose.yml`, Sail invocation, repo documentation, MCP or agent configs, editor tasks, and rollback or smoke validation.

Key approach: move all app-owned Laravel files together, keep `docker-compose.yml` at repo root, let app-local Sail target the root compose file via `SAIL_FILES`, mount only `./apps/platform` into the application containers, and update every repo-level command surface to either `cd apps/platform && ...` or transparently delegate there. Filament remains v5 on Livewire v4, provider registration remains in `apps/platform/bootstrap/providers.php`, no global-search contract changes are introduced, no destructive action semantics change, and deployment keeps the existing `php artisan filament:assets` step executed from `apps/platform`.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12, Blade, Livewire v4, Filament v5.2.x, Tailwind CSS v4, Vite 7  
**Primary Dependencies**: `laravel/framework`, `filament/filament`, `livewire/livewire`, `laravel/sail`, `laravel-vite-plugin`, `tailwindcss`, `vite`, `pestphp/pest`, `drizzle-kit`, PostgreSQL, Redis, Docker Compose  
**Storage**: PostgreSQL, Redis, filesystem storage under the Laravel app `storage/` tree, plus existing Vite build artifacts in `public/build`; no new database persistence planned  
**Testing**: Pest v4 feature, unit, and browser tests plus PHPUnit config files, all executed through Sail after relocation  
**Target Platform**: Containerized Laravel web app and queue workers for local Sail on macOS and Linux containers in staging or production
**Project Type**: Laravel monolith relocated under a repo-root orchestration layer  
**Performance Goals**: Preserve current boot, asset-build, queue-worker, and panel-load behavior; keep clean-checkout setup within the success criteria window; avoid extra path-indirection layers in runtime code  
**Constraints**: No product behavior changes; no `apps/website`; no shared packages; no pnpm, Turbo, Nx, or CI/CD rebuild in this slice; one official command model only; root `docker-compose.yml` remains repo-level; external deploy assumptions must stay explicit  
**Scale/Scope**: One full-app relocation affecting every Laravel-owned directory and app-local tooling file, plus root docs, tasks, agent configs, compose wiring, smoke validation, and rollback guidance

## Constitution Check

*GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.*

| Principle | Status | Notes |
|-----------|--------|-------|
| Inventory-first | Pass | No inventory or snapshot ownership changes; only repo topology changes |
| Read/write separation | Pass | No new product mutation flow is introduced |
| Graph contract path | Pass | No Graph endpoint or contract registry change |
| Deterministic capabilities | Pass | Capability registry and RBAC remain unchanged |
| RBAC-UX planes and 404 vs 403 | Pass | `/admin`, `/admin/t/{tenant}/...`, and `/system` semantics must remain identical after relocation |
| Workspace isolation | Pass | No workspace-context broadening or alternate route path is introduced |
| Tenant isolation | Pass | Tenant-scoped routes remain tenant-scoped; relocation must not bypass existing guards |
| Global search safety | Pass | No searchable resource behavior is changed; any existing global-search contract remains as-is |
| Dangerous and destructive confirmations | Pass | No new destructive actions or placement changes are part of this slice |
| Run observability | Pass | Existing queued and remote flows keep current `OperationRun` semantics; smoke pack explicitly validates queue startup and run-adjacent runtime integrity |
| Ops-UX 3-surface feedback | Pass | Existing operation feedback flows remain unchanged because no operation UX redesign is introduced |
| Data minimization | Pass | No new logs, payload mirrors, or extra persisted truth are added |
| Proportionality (PROP-001) | Pass | The plan avoids website apps, workspaces, packages, and orchestration frameworks |
| No premature abstraction (ABSTR-001) | Pass | No new platform engine or repo framework is introduced; only relocation contracts and narrow delegation helpers are allowed |
| Persisted truth (PERSIST-001) | Pass | No new table or artifact source of truth is introduced |
| Behavioral state (STATE-001) | Pass | No new status or reason-code family is added |
| UI semantics (UI-SEM-001) | Pass | No new presentation layer or UI framework is introduced |
| Filament-native UI (UI-FIL-001) | Pass | Existing Filament pages and themes remain authoritative; only path resolution changes |
| Filament v5 / Livewire v4 compliance | Pass | The relocation keeps Filament v5 on Livewire v4 with no API downgrades or legacy mix-in |
| Provider registration location | Pass | Panel providers remain registered in `bootstrap/providers.php`, which simply moves with the app to `apps/platform/bootstrap/providers.php` |
| Global search hard rule | Pass | The move does not remove Edit or View pages from any globally searchable resource and does not enable search for any previously disabled resource |
| Asset strategy | Pass | Existing Vite-compiled assets and Filament themes remain app-local; deployment continues to run `php artisan filament:assets` from `apps/platform` |
| Testing plan | Pass | Validation covers public entry, admin or tenant or system panels, queue worker startup, build chain, and focused Pest smoke through Sail |

## Phase 0 Research

Research outcomes are captured in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/182-platform-relocation/research.md`.

Key decisions:

- Move the whole Laravel project into `apps/platform` so internal relative paths in `artisan`, `public/index.php`, `bootstrap/app.php`, PHPUnit bootstrap, Vite inputs, Tailwind `@source`, Filament theme imports, and Drizzle stay stable.
- Keep `apps/platform` as the one canonical working directory for platform development commands.
- Keep `docker-compose.yml` at repo root and bridge app-local Sail to it via `SAIL_FILES`, which the current Sail script already supports.
- Mount only `./apps/platform` into `/var/www/html` for the web and queue services so runtime commands execute against the relocated app, not the whole repo.
- Keep application config truth in `apps/platform/.env`, allowing only compose-specific variables outside the app when strictly necessary.
- Move app-local tooling files such as `composer.json`, `package.json`, `vite.config.js`, `phpunit*.xml`, and `drizzle.config.ts` with the app while leaving repo-wide docs, tasks, MCP config, and agent config at root.
- Treat Dokploy build context, production working directory, volume mapping, and unpublished operator wrappers as explicit rollout questions rather than implicit assumptions.

## Phase 1 Design

Design artifacts are created under `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/182-platform-relocation/`:

- `data-model.md`: logical relocation artifacts, ownership boundaries, and validation rules
- `contracts/local-command-model.md`: canonical developer command and delegation contract
- `contracts/runtime-smoke.openapi.yaml`: preserved HTTP surface contract for relocation smoke validation
- `quickstart.md`: implementation-time smoke and rollback validation workflow

Design decisions:

- No schema migration is required; this is a repo topology and runtime-path slice only.
- Because the whole app moves together, Laravel bootstrap files, Filament providers, Vite config, PHPUnit config, Tailwind theme files, and Drizzle config largely stay intact relative to the app root.
- The main runtime changes occur at repo-root orchestration boundaries: `docker-compose.yml`, env bridging for Sail, root-level wrappers or docs, editor tasks, MCP config, and agent guidance.
- Root command references are broad and include `README.md`, `Agents.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.vscode/mcp.json`, `opencode.json`, and many `tasks.json` entries; these must be normalized to the single official command model or deliberate root delegators.
- Existing Filament panels remain panel-local Vite theme consumers; `php artisan filament:assets` stays part of deploy execution from `apps/platform`.

## Project Structure

### Documentation (this feature)

```text
specs/182-platform-relocation/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── local-command-model.md
│   └── runtime-smoke.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md
```

### Source Code (repository root)
```text
repo-root/
├── apps/
│   └── platform/
│       ├── app/
│       ├── bootstrap/
│       ├── config/
│       ├── database/
│       ├── public/
│       ├── resources/
│       ├── routes/
│       ├── storage/
│       ├── tests/
│       ├── artisan
│       ├── composer.json
│       ├── package.json
│       ├── vite.config.js
│       ├── phpunit.xml
│       ├── phpunit.pgsql.xml
│       ├── drizzle.config.ts
│       └── .env.example
├── docs/
├── specs/
├── scripts/
├── .specify/
├── .github/
├── .vscode/
├── docker-compose.yml
├── README.md
├── Agents.md
├── GEMINI.md
├── boost.json
└── opencode.json
```

**Structure Decision**: Repo-root orchestration plus one Laravel monolith under `apps/platform`. The whole app moves together so app-local pathing stays coherent. No additional app, shared package, or workspace tooling layer is introduced.

## Implementation Strategy

### Phase A — Establish The File Placement Contract And App Root

**Goal**: Move the full Laravel app as one unit and eliminate the hybrid root-plus-app state.

| Step | Area | Change |
|------|------|--------|
| A.1 | App root | Create `apps/platform` and move all Laravel-owned directories and files there: `app`, `bootstrap`, `config`, `database`, `public`, `resources`, `routes`, `storage`, `tests`, `artisan`, `composer.json`, `package.json`, `vite.config.js`, `phpunit*.xml`, `drizzle.config.ts`, `.env.example` |
| A.2 | Root cleanup | Remove repo-root authority for moved Laravel structures and keep only repo-level docs, scripts, tooling, and orchestration files |
| A.3 | Placement matrix | Publish the file-placement contract in maintained docs and document reviewed exceptions such as `.gitignore`, `.dockerignore`, and any retained root helper or wrapper |

### Phase B — Rewire Docker, Sail, And Runtime Boundaries

**Goal**: Keep the repo root as orchestration while letting the relocated app run as if it were still a normal Laravel project root.

| Step | Area | Change |
|------|------|--------|
| B.1 | Compose | Update root `docker-compose.yml` so web and queue services mount `./apps/platform` into `/var/www/html` and execute commands against the relocated app |
| B.2 | Sail bridge | Use Sail's existing `SAIL_FILES` support so `apps/platform/vendor/bin/sail` can target the repo-root compose file without making root the official working directory |
| B.3 | Env model | Keep app config in `apps/platform/.env`; isolate any compose-only variables outside the canonical app config truth |
| B.4 | Queue and runtime | Validate queue commands, storage paths, Vite port wiring, and node_modules volume behavior under the relocated mount |

### Phase C — Align Build, Test, And Tooling Surfaces

**Goal**: Make every maintained command surface either app-local or an explicit delegator.

| Step | Area | Change |
|------|------|--------|
| C.1 | Build and test config | Preserve or minimally adjust moved `vite.config.js`, Tailwind theme sources, `phpunit.xml`, `phpunit.pgsql.xml`, Composer scripts, and Drizzle config so they work from `apps/platform` |
| C.2 | MCP and agent config | Update root `.vscode/mcp.json`, `opencode.json`, agent instructions, and related tooling to call `apps/platform` commands or wrappers explicitly |
| C.3 | VS Code tasks | Normalize `tasks.json` to the new app path and use the relocation to repair the current root-coupled task surface rather than layering more absolute-path tasks |
| C.4 | Documentation | Update `README.md`, `Agents.md`, `GEMINI.md`, and other root guidance to the single official command model |

### Phase D — Define Rollback And Branch Safety

**Goal**: Make the move recoverable and merge-aware.

| Step | Area | Change |
|------|------|--------|
| D.1 | Rollback | Document git rollback, env relocation recovery, dependency rebuild, build artifact cleanup, Docker cleanup, and worker recovery |
| D.2 | Branch guidance | Document open-branch merge expectations and the communication required before landing the topology move |
| D.3 | External unknowns | Capture Dokploy and production working-directory questions separately from the code move so rollout is blocked on evidence, not on guesswork |

### Phase E — Execute Smoke Validation

**Goal**: Prove the relocated topology works end-to-end before rollout.

| Step | Area | Change |
|------|------|--------|
| E.1 | Local boot | Verify install, Sail startup, CLI bootstrap, and the public health or entry endpoints |
| E.2 | Build and panels | Verify Vite build, manifest resolution, Filament admin, choose-workspace navigation, a representative tenant route with preserved `404` versus `403` semantics, and system panels and theme loading |
| E.3 | Queue and tests | Verify queue worker startup, a representative queued flow, and a focused Sail-driven Pest smoke pack |
| E.4 | Tooling | Verify at least one VS Code task or MCP or agent-assisted command path works under the relocated model and capture timing evidence for setup and rollback success criteria |

## Key Design Decisions

### D-001 — Move The Whole Laravel App, Not A Split Root/App Hybrid

The relocation moves app-owned files together so Laravel, Vite, Tailwind, PHPUnit, Filament theme imports, and Drizzle continue to resolve relative paths from one coherent app root.

### D-002 — `apps/platform` Remains The Official Working Directory Even With Root Compose

The root keeps `docker-compose.yml`, but app-local Sail bridges to it using `SAIL_FILES`, which the current Sail script already supports. This preserves the spec's app-first command model without forcing compose back into the app directory.

### D-003 — Root Helpers Are Compatibility Only, Never A Second Primary Workflow

Any retained root wrappers or task aliases must do nothing except delegate into `apps/platform`. The plan forbids a dual-workflow state where root and app commands are equally official.

### D-004 — Application Env Truth Lives In `apps/platform`

`apps/platform/.env` remains the canonical Laravel environment file. Compose-specific values may exist outside the app only when they are orchestration concerns rather than application config truth.

### D-005 — This Slice Stops At Topology And Runtime Safety

No website app, no shared package layer, no workspace tooling, and no CI/CD redesign enter the implementation plan. The only acceptable complexity is what is needed to relocate the existing platform app safely.

## Risk Assessment

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Sail cannot find the repo-root compose file when run from `apps/platform` | High | Medium | Bridge with `SAIL_FILES`, document it in `.env.example`, and validate the exact command flow in smoke tests |
| Compose mounts the wrong directory, so web boots or queue workers run against stale root paths | High | Medium | Mount only `./apps/platform`, verify worker command resolution, and include queue smoke in validation |
| Repo docs and agent configs continue to recommend root-relative `vendor/bin/sail` and `artisan` commands | High | High | Update all maintained docs and configs in the same slice and verify at least one MCP or task flow |
| `tasks.json` and other editor automation contain stale absolute root paths or malformed task definitions | Medium | High | Treat tooling normalization as part of the implementation, not a follow-up |
| External deploy assumptions differ from local Sail behavior | High | Medium | Keep Dokploy questions explicit and block rollout on verified answers rather than implicit parity |
| Open branches encounter large merge churn after the topology move lands | Medium | High | Include explicit branch and rollback guidance in the rollout notes |

## Test Strategy

- Validate the relocated stack with Sail from `apps/platform`, not by ad-hoc root shell commands.
- Run CLI smoke through the relocated app: version or about, `migrate:status`, and a queue-related artisan command.
- Run build smoke through the relocated app: `npm run build` and, where needed, `npm run dev` validation for HMR and manifest resolution.
- Run preserved HTTP surface smoke for the public entry, admin shell, workspace chooser, one representative tenant-scoped route, one deny-as-not-found tenant access path, and the system shell using the contract in `contracts/runtime-smoke.openapi.yaml`.
- Validate Filament v5 and Livewire v4 compliance by loading existing admin, tenant, and system panels after relocation; no new page or relation-manager tests are required because no operator surface behavior changes are introduced.
- Run a focused Sail-driven Pest smoke pack from the relocated app. Existing tests remain the primary regression guard; the relocation does not require new domain behavior tests unless a runtime-specific regression appears.
- Validate queue integrity by starting the queue container and exercising one representative queued flow or command path under the relocated topology.
- Validate at least one tooling flow such as `.vscode/mcp.json` or a repaired VS Code task so repo automation does not drift behind the app move.
- Capture elapsed setup and rollback timings according to the quickstart measurement protocol so the time-based success criteria are reviewable instead of anecdotal.
- Preserve deployment asset behavior by keeping `php artisan filament:assets` in the deployment flow executed from `apps/platform`.

## Complexity Tracking

No constitution violations or exception-driven complexity are expected. The plan deliberately rejects shared packages, workspace tooling, and multi-app orchestration to keep the relocation proportional.

## Proportionality Review

- **Current operator problem**: The repo root currently conflates application runtime and repo orchestration, which increases path ambiguity today and blocks a clean multi-app topology tomorrow.
- **Existing structure is insufficient because**: Every maintained command, task, and container assumes the Laravel app is the repo root. That prevents root from acting as an independent repo layer.
- **Narrowest correct implementation**: Move the whole existing app into `apps/platform`, rewire root orchestration, document one command model, and validate with smoke plus rollback.
- **Ownership cost created**: A broad but mechanical path migration across compose, docs, tasks, and tool configs, plus rollback and branch communication discipline.
- **Alternative intentionally rejected**: A larger monorepo introduction with website apps, shared packages, workspace tooling, or CI/CD redesign. It solves a different problem and creates unnecessary ownership cost now.
- **Release truth**: Current-release infrastructure truth that prepares future surfaces without shipping them in this slice.