ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
ce0615a9c1
TenantAtlas/specs/182-platform-relocation/tasks.md
ahmido ce0615a9c1 Spec 182: relocate Laravel platform to apps/platform (#213) 
## Summary
- move the Laravel application into `apps/platform` and keep the repository root for orchestration, docs, and tooling
- update the local command model, Sail/Docker wiring, runtime paths, and ignore rules around the new platform location
- add relocation quickstart/contracts plus focused smoke coverage for bootstrap, command model, routes, and runtime behavior

## Validation
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/PlatformRelocation`
- integrated browser smoke validated `/up`, `/`, `/admin`, `/admin/choose-workspace`, and tenant route semantics for `200`, `403`, and `404`

## Remaining Rollout Checks
- validate Dokploy build context and working-directory assumptions against the new `apps/platform` layout
- confirm web, queue, and scheduler processes all start from the expected working directory in staging/production
- verify no legacy volume mounts or asset-publish paths still point at the old root-level `public/` or `storage/` locations

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #213
2026-04-08 08:40:47 +00:00

235 lines
15 KiB
Markdown
Raw Blame History

# Tasks: Platform Relocation to apps/platform
**Input**: Design documents from `/specs/182-platform-relocation/`
**Prerequisites**: `plan.md` (required), `spec.md` (required for user stories), `research.md`, `data-model.md`, `contracts/`, `quickstart.md`
**Tests**: Tests are REQUIRED for this feature. Use focused Pest coverage under `apps/platform/tests/Feature/PlatformRelocation/` plus the documented smoke validation from `specs/182-platform-relocation/quickstart.md`.
**Operations**: This feature does not introduce a new `OperationRun` type or change existing operations UX semantics. Queue and worker smoke validation is still required because the relocation changes runtime pathing for existing queued flows.
**RBAC**: No authorization model changes are allowed. Smoke and regression validation must preserve existing `404` versus `403` behavior on `/admin`, `/admin/t/{tenant}/...`, and `/system` routes after the move.
**Operator Surfaces**: No operator-surface redesign is part of this slice. Existing public, admin, tenant, and system surfaces must continue to render with the same route and authorization semantics after relocation.
**Filament UI Action Surfaces**: No new Filament action surfaces are introduced. Existing resources and pages must continue to work unchanged once the app runs from `apps/platform`.
**Filament UI UX-001**: No layout or information-architecture redesign is part of this feature. Filament panels, themes, and existing surface contracts must remain intact.
**Badges**: No badge semantics change is planned. Existing badge rendering must continue to work after relocation.
**Organization**: Tasks are grouped by user story so each story can be implemented and validated as an independent increment after the blocking relocation groundwork is complete.
## Phase 1: Setup (Shared Relocation Scaffolding)
**Purpose**: Prepare the target app root and shared relocation-specific scaffolding before moving the app.
- [X] T001 Create the relocated app root scaffold under `apps/platform/` and reserve the repo-root orchestration layer in `apps/platform/` and `.gitignore`
- [X] T002 [P] Create the relocation smoke test namespace in `apps/platform/tests/Feature/PlatformRelocation/`
- [X] T003 [P] Create the compatibility-only Sail delegation helper scaffold in `scripts/platform-sail`
---
## Phase 2: Foundational (Blocking Prerequisites)
**Purpose**: Complete the blocking file move and runtime boundary changes before any story-specific work begins.
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
- [X] T004 Move all Laravel-owned runtime directories and files into `apps/platform/app/`, `apps/platform/bootstrap/`, `apps/platform/config/`, `apps/platform/database/`, `apps/platform/public/`, `apps/platform/resources/`, `apps/platform/routes/`, `apps/platform/storage/`, `apps/platform/tests/`, `apps/platform/artisan`, `apps/platform/composer.json`, `apps/platform/package.json`, `apps/platform/vite.config.js`, `apps/platform/phpunit.xml`, `apps/platform/phpunit.pgsql.xml`, `apps/platform/drizzle.config.ts`, and `apps/platform/.env.example`
- [X] T005 Update compose mounts, build contexts, and queue command resolution for the relocated app in `docker-compose.yml`
- [X] T006 [P] Re-home app env ownership and PHPUnit bootstrap configuration in `apps/platform/.env.example`, `apps/platform/phpunit.xml`, and `apps/platform/phpunit.pgsql.xml`
- [X] T007 [P] Add foundational relocated-app bootstrap-path smoke coverage in `apps/platform/tests/Feature/PlatformRelocation/BootstrapPathSmokeTest.php`
- [X] T008 Align repo-level ignore and boundary files with the new topology in `.gitignore` and `.dockerignore`
**Checkpoint**: The Laravel app now lives only in `apps/platform`, and the repo root is ready to act as orchestration only.
---
## Phase 3: User Story 1 - Run the Platform From the New Location (Priority: P1) 🎯 MVP
**Goal**: Make `apps/platform` the one official local command model for install, boot, build, and test workflows.
**Independent Test**: Starting from a clean checkout, a developer can follow the documented workflow in `apps/platform` and reach a running application plus a passing focused smoke run without ad-hoc path fixes.
### Tests for User Story 1
- [X] T009 [P] [US1] Add command-model smoke coverage for app-local Sail delegation and CLI bootstrap in `apps/platform/tests/Feature/PlatformRelocation/CommandModelSmokeTest.php`
### Implementation for User Story 1
- [X] T010 [US1] Implement the app-local Sail compose bridge in `apps/platform/.env.example` and `scripts/platform-sail`
- [X] T011 [P] [US1] Normalize developer install, build, and test commands in `apps/platform/composer.json` and `apps/platform/package.json`
- [X] T012 [P] [US1] Update the canonical setup, file-placement contract, and command documentation in `README.md` and `specs/182-platform-relocation/quickstart.md`
- [X] T013 [US1] Align human and assistant guidance to the single `apps/platform` workflow in `Agents.md`, `GEMINI.md`, and `.github/copilot-instructions.md`
- [X] T014 [US1] Run and time the clean-checkout command flow from `specs/182-platform-relocation/quickstart.md`
**Checkpoint**: The repo now has one official local workflow, centered on `apps/platform`.
---
## Phase 4: User Story 2 - Keep Existing Runtime Surfaces Stable (Priority: P1)
**Goal**: Preserve public entry, panels, assets, and queue-backed runtime behavior after the move.
**Independent Test**: The relocated app boots through Sail, serves the public and Filament shells, preserves choose-workspace and representative tenant-route behavior including `404` versus `403` semantics, builds assets correctly, and runs a representative queue-backed flow without root-path errors.
### Tests for User Story 2
- [X] T015 [P] [US2] Add preserved HTTP surface and authorization smoke coverage for `/`, `/admin`, `/admin/choose-workspace`, `/admin/t/{tenant}/backup-sets`, and `/system`, including expected `404` versus `403` behavior, in `apps/platform/tests/Feature/PlatformRelocation/PanelRouteSmokeTest.php`
- [X] T016 [P] [US2] Add queue and runtime smoke coverage for health, storage, and worker boot in `apps/platform/tests/Feature/PlatformRelocation/RuntimeSmokeTest.php`
### Implementation for User Story 2
- [X] T017 [US2] Preserve bootstrap and public-entry behavior in `apps/platform/artisan`, `apps/platform/bootstrap/app.php`, and `apps/platform/public/index.php`
- [X] T018 [P] [US2] Re-home Vite inputs and Tailwind or Filament theme source scanning in `apps/platform/vite.config.js`, `apps/platform/resources/css/filament/admin/theme.css`, and `apps/platform/resources/css/filament/system/theme.css`
- [X] T019 [P] [US2] Preserve Filament provider registration and panel asset integrity in `apps/platform/bootstrap/providers.php`, `apps/platform/app/Providers/Filament/AdminPanelProvider.php`, `apps/platform/app/Providers/Filament/TenantPanelProvider.php`, and `apps/platform/app/Providers/Filament/SystemPanelProvider.php`
- [X] T020 [US2] Finalize container runtime, queue worker, and node_modules handling in `docker-compose.yml`
- [X] T021 [US2] Run the runtime smoke pack from `specs/182-platform-relocation/quickstart.md` against build, panel, workspace-selection, route-semantics, tenant-route authorization, and queue flows
**Checkpoint**: The relocated app serves the same runtime surfaces and background behavior as before the move.
---
## Phase 5: User Story 3 - Review and Roll Back the Move Safely (Priority: P2)
**Goal**: Provide a realistic rollback path, open-branch guidance, and visible deployment unknowns for the topology move.
**Independent Test**: A maintainer can read the rollout docs and understand how to revert the move locally, clean up dependencies and Docker state, and communicate branch impact without reverse-engineering the implementation.
### Implementation for User Story 3
- [X] T022 [US3] Document git rollback and local environment recovery in `README.md` and `specs/182-platform-relocation/quickstart.md`
- [X] T023 [P] [US3] Document branch-impact, merge, and rebase guidance for the topology move in `Agents.md` and `docs/HANDOVER.md`
- [X] T024 [P] [US3] Capture external deployment unknowns and rollout gates in `docs/HANDOVER.md` and `README.md`
- [X] T025 [US3] Validate rollback notes and rollback timing evidence against relocated env, vendor, node_modules, and Docker cleanup paths in `specs/182-platform-relocation/quickstart.md`
**Checkpoint**: Rollback and rollout risk are explicit, reviewable, and grounded in the relocated path structure.
---
## Phase 6: User Story 4 - Keep Repo Tooling Aligned With the New Topology (Priority: P3)
**Goal**: Ensure repo-level tooling, tasks, and MCP launchers target the relocated app correctly.
**Independent Test**: At least one MCP flow and one VS Code task succeed against the relocated app without manual path correction.
### Implementation for User Story 4
- [X] T026 [P] [US4] Repoint repo-level MCP launchers to the relocated app in `.vscode/mcp.json` and `opencode.json`
- [X] T027 [US4] Normalize maintained VS Code task commands to delegate into `apps/platform` or `scripts/platform-sail` in `.vscode/tasks.json`
- [X] T028 [P] [US4] Align assistant context and workspace automation assumptions with the relocated path model in `.github/agents/copilot-instructions.md` and `.github/copilot-instructions.md`
- [X] T029 [US4] Validate one MCP flow and one VS Code task from `specs/182-platform-relocation/quickstart.md`
**Checkpoint**: Repo tooling no longer assumes the Laravel app lives at repo root.
---
## Phase 7: Polish & Cross-Cutting Concerns
**Purpose**: Remove stale references, format touched files, and finish the full smoke pass.
- [X] T030 [P] Remove stale root-relative platform command references across `README.md`, `Agents.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.vscode/tasks.json`, `.vscode/mcp.json`, and `opencode.json`
- [X] T031 [P] Run formatting for relocated PHP and config changes using the workflow documented in `specs/182-platform-relocation/quickstart.md`
- [X] T032 [P] Run the focused relocation Pest smoke suite in `apps/platform/tests/Feature/PlatformRelocation/`
- [X] T033 Run the full documented smoke validation and capture final rollout evidence, including setup and rollback timing proof, from `specs/182-platform-relocation/quickstart.md`
---
## Dependencies & Execution Order
### Phase Dependencies
- **Setup (Phase 1)**: Starts immediately and prepares the target directory and shared scaffolding.
- **Foundational (Phase 2)**: Depends on Setup and blocks all user stories until the app move and compose boundary work are complete.
- **User Story 1 (Phase 3)**: Starts after Foundational and establishes the official command model.
- **User Story 2 (Phase 4)**: Starts after Foundational and should be completed alongside or immediately after User Story 1 because runtime validation depends on the new command model.
- **User Story 3 (Phase 5)**: Starts after User Stories 1 and 2 because rollback and rollout guidance must reflect the final relocated runtime.
- **User Story 4 (Phase 6)**: Starts after User Story 1 because tooling should target the finalized command model and helper strategy.
- **Polish (Phase 7)**: Starts after all desired user stories are complete.
### User Story Dependencies
- **US1**: Depends only on Setup and Foundational work.
- **US2**: Depends on Setup and Foundational work and should reuse the command model established in US1.
- **US3**: Depends on US1 and US2 so rollback and rollout notes describe the final relocated runtime.
- **US4**: Depends on US1 so tooling delegates to the canonical app-local workflow rather than a temporary path.
### Within Each User Story
- Tests or validation coverage should be added before the corresponding story is considered complete.
- File-move and compose changes must land before docs or tooling that depend on the relocated paths.
- Focused smoke validation should pass before moving to the next story or phase.
### Parallel Opportunities
- `T002` and `T003` can run in parallel during Setup.
- `T006` and `T007` can run in parallel once `T004` establishes the relocated app root.
- `T009`, `T011`, and `T012` can run in parallel for US1 after the Sail bridge direction is fixed.
- `T015`, `T016`, `T018`, and `T019` can run in parallel for US2 once bootstrap paths are stable.
- `T023` and `T024` can run in parallel for US3.
- `T026` and `T028` can run in parallel for US4.
- `T030`, `T031`, and `T032` can run in parallel during Polish.
---
## Parallel Example: User Story 1
```bash
# Story 1 command-model work in parallel:
Task: T009 apps/platform/tests/Feature/PlatformRelocation/CommandModelSmokeTest.php
Task: T011 apps/platform/composer.json and apps/platform/package.json
Task: T012 README.md and specs/182-platform-relocation/quickstart.md
```
## Parallel Example: User Story 2
```bash
# Story 2 runtime work in parallel:
Task: T015 apps/platform/tests/Feature/PlatformRelocation/PanelRouteSmokeTest.php
Task: T016 apps/platform/tests/Feature/PlatformRelocation/RuntimeSmokeTest.php
Task: T018 apps/platform/vite.config.js and apps/platform/resources/css/filament/*/theme.css
Task: T019 apps/platform/bootstrap/providers.php and apps/platform/app/Providers/Filament/*.php
```
## Parallel Example: User Story 4
```bash
# Story 4 tooling work in parallel:
Task: T026 .vscode/mcp.json and opencode.json
Task: T028 .github/agents/copilot-instructions.md and .github/copilot-instructions.md
```
---
## Implementation Strategy
### MVP First
1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Complete Phase 4: User Story 2.
5. **STOP and VALIDATE**: Run the focused smoke pack and confirm the relocated app boots, serves panels, and runs queue-backed behavior.
### Incremental Delivery
1. Finish Setup and Foundational to establish the relocated app root.
2. Deliver US1 to lock the canonical command model.
3. Deliver US2 to prove runtime integrity.
4. Deliver US3 to document rollback and rollout boundaries.
5. Deliver US4 to align repo tooling and automation.
### Parallel Team Strategy
With multiple developers:
1. Complete Setup and Foundational together.
2. After Foundational:
- Developer A: US1 command model and documentation
- Developer B: US2 runtime and panel smoke
3. After US1 is stable:
- Developer C: US4 tooling and MCP alignment
4. After US1 and US2 are stable:
- Developer D: US3 rollback and rollout documentation
---
## Notes
- Suggested MVP scope for this feature is **US1 + US2**, not US1 alone, because a repository-topology move is only viable when the canonical command model and the relocated runtime both work.
- Keep any root-level helper explicitly labeled as compatibility-only so the repo does not drift back into a dual-workflow state.
Reference in New Issue View Git Blame Copy Permalink