# 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

```bash
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:

```bash
./scripts/platform-sail up -d
```

## CLI Smoke

```bash
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

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

Optional dev-server check:

```bash
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

```bash
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`:

```bash
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

```bash
# 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?