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

Quickstart: Platform Relocation to apps/platform

Purpose

Use this guide after implementation to verify that the relocated platform app boots, serves assets, runs queue workers, passes focused tests, and still works with repo tooling.

Prerequisites

1. Start from a clean checkout on 182-platform-relocation.
2. Ensure the relocated app exists at apps/platform.
3. Ensure the app env has the compose bridge configured if Sail requires it, for example through SAIL_FILES pointing to the repo-root docker-compose.yml.

File Placement Contract Check

Before runtime validation, confirm the published topology contract is still true:

1. Repo root owns repo-wide docs, specs, scripts, editor settings, agent config, and docker-compose.yml.
2. apps/platform owns Laravel runtime files, application code, tests, build inputs, public entry files, and app-local env files.
3. Reviewed root-level exceptions such as .gitignore, .dockerignore, and scripts/platform-sail are documented as orchestration or compatibility-only concerns rather than a second application root.

Timing And Evidence Capture

Use this protocol when validating the time-based success criteria:

1. For setup timing, start the clock at the first documented setup command with no apps/platform/.env, apps/platform/vendor/, apps/platform/node_modules/, or app build artifacts present.
2. Stop the setup clock when the CLI smoke passes and http://localhost/admin/choose-workspace returns the expected pre-move auth or workspace-selection response.
3. For rollback timing, start the clock at the first documented rollback command and stop when rollback cleanup is complete and the restored local workflow reaches its documented sanity state.
4. Record the operating system, container runtime, whether Docker images were already available locally, and any intentionally skipped optional checks.

Canonical Setup Flow

cd apps/platform
composer install
cp .env.example .env
./vendor/bin/sail up -d
./vendor/bin/sail artisan key:generate
./vendor/bin/sail artisan migrate

Compatibility-only root helper for repo tooling:

./scripts/platform-sail up -d

CLI Smoke

cd apps/platform
./vendor/bin/sail artisan --version
./vendor/bin/sail artisan migrate:status
./vendor/bin/sail artisan about

Expected outcome:

• Laravel boots from apps/platform.
• Artisan resolves the relocated app without manual path overrides.
• Database connectivity is intact.

Build Smoke

cd apps/platform
./vendor/bin/sail npm run build

Optional dev-server check:

cd apps/platform
./vendor/bin/sail npm run dev

Expected outcome:

• Vite builds without missing manifest or path-resolution failures.
• Filament theme assets still resolve from the relocated app.

Web And Panel Smoke

Check these routes in a browser after the stack is up:

1. http://localhost/up
2. http://localhost/
3. http://localhost/admin
4. http://localhost/admin/choose-workspace
5. One representative entitled tenant route such as http://localhost/admin/t/{tenant}/backup-sets
6. One representative non-member or wrong-scope tenant route that should still deny as not found (404)
7. http://localhost/system

Expected outcome:

• No 500 error caused by base-path, manifest, or storage path resolution.
• Auth redirects remain consistent with pre-move behavior.
• Choose-workspace navigation and a representative tenant navigation path resolve without broken assets or stale root-path assumptions.
• Tenant authorization semantics remain consistent with pre-move behavior, including preserved 404 versus 403 outcomes for the validated route fixtures.
• Admin, tenant, and system shells load with the expected assets.

Auth, Workspace, And Route-Semantics Smoke

Validate these behaviors explicitly as part of the smoke pack:

1. /admin reaches the same login or auth-gate behavior as before the move.
2. /admin/choose-workspace preserves the existing chooser or redirect behavior.
3. A representative entitled tenant route loads through the relocated app without route or asset regressions.
4. Automated route smoke preserves deny-as-not-found (404) for non-member tenant access and preserves capability-only (403) denials where those fixtures already exist.

Queue Smoke

cd apps/platform
./vendor/bin/sail ps
./vendor/bin/sail logs queue --tail=50

Then execute one representative queue-backed platform flow and verify that the queue worker handles it without root-path errors.

Test Smoke

Run the smallest focused relocation regression pack available after implementation. At minimum, execute a compact Pest smoke run from apps/platform:

cd apps/platform
./vendor/bin/sail artisan test --compact

If the implementation introduces a smaller relocation-focused pack in tasks.md, run that first and then decide whether a full compact run is necessary.

Tooling Smoke

Validate at least one repo-level tool flow after the move:

1. One repaired VS Code task that delegates to apps/platform
2. One MCP flow via .vscode/mcp.json or opencode.json

Expected outcome:

• The tool resolves the relocated app path explicitly.
• No hidden root-relative vendor/bin/sail or artisan assumption remains.

Rollback Flow

# Preserve any local app env changes you still need
cp apps/platform/.env /tmp/tenantatlas.platform.env.backup

# Stop and clean local runtime state
cd apps/platform
./vendor/bin/sail down -v
cd ../..
rm -rf apps/platform/vendor apps/platform/node_modules apps/platform/public/build
rm -f apps/platform/public/hot

Then revert the relocation commit on your working branch, restore the correct env file for the restored topology, and rerun the documented setup flow for that revision.

Rollback Readiness Check

Before rollout approval, confirm the documentation covers:

1. Git rollback steps
2. .env recovery
3. vendor/, node_modules, and build artifact cleanup
4. Docker cleanup or volume recovery
5. Open-branch communication for rebases or merges
6. Timing evidence for setup and rollback success criteria

External Rollout Questions

1. Does Dokploy build from repo root while running Laravel commands from apps/platform?
2. Which working directory do the staging and production web, queue, and scheduler processes use after the move?
3. Do any existing Dokploy volume mounts or asset-publish steps still point at the pre-move root public/ or storage/ trees?