# Research: Platform Relocation to apps/platform

## Decision 1

- **Decision**: Move the entire Laravel application into `apps/platform`, including `composer.json`, `package.json`, `vite.config.js`, `phpunit*.xml`, `drizzle.config.ts`, `public/`, `bootstrap/`, and `.env.example`.
- **Rationale**: Moving the whole project root together preserves existing internal relative-path assumptions in `artisan`, `public/index.php`, `bootstrap/app.php`, PHPUnit bootstrap, Vite inputs, Tailwind `@source`, Filament theme imports, and Drizzle config. That minimizes risky bootstrap edits.
- **Alternatives considered**:
  - Keep Composer or `vendor/` at repo root and move only app code: rejected because it forces cross-root bootstrap rewiring and increases long-term ambiguity.
  - Leave `public/` or `bootstrap/` at root: rejected because it creates a hybrid steady state that violates the structure contract.

## Decision 2

- **Decision**: Make `apps/platform` the single official working directory for platform development commands.
- **Rationale**: One command model is clearer than a split root-plus-app workflow and matches the long-term goal of turning root into a real orchestration layer.
- **Alternatives considered**:
  - Root-wrapper-first workflow: rejected because it preserves root as the mental app root.
  - Dual official workflows: rejected because it guarantees documentation and tooling drift.

## Decision 3

- **Decision**: Keep `docker-compose.yml` at repo root and let app-local Sail load it through `SAIL_FILES`.
- **Rationale**: The current Sail script already supports `SAIL_FILES`. This allows `apps/platform/vendor/bin/sail` to stay the canonical launcher while root remains the orchestration layer.
- **Alternatives considered**:
  - Move `docker-compose.yml` into `apps/platform`: rejected because the spec explicitly keeps compose at root.
  - Make root the only supported Sail entrypoint: rejected because it conflicts with the chosen official command model.

## Decision 4

- **Decision**: Update root compose services to mount `./apps/platform` into `/var/www/html` for both web and queue containers.
- **Rationale**: Container runtime, queue commands, vendor binaries, and build outputs should operate against the relocated app only, not the whole repo tree.
- **Alternatives considered**:
  - Mount the entire repo and `cd` into `apps/platform` inside commands: rejected because it keeps stale root assumptions alive and complicates worker commands.
  - Use symlinks from root back into the app: rejected because it obscures ownership and rollback.

## Decision 5

- **Decision**: Keep `apps/platform/.env` and `apps/platform/.env.example` as the canonical Laravel environment files; any root env file must be compose-only.
- **Rationale**: Application config truth should live with the application. Root-level env data should exist only if compose itself needs separate variables.
- **Alternatives considered**:
  - Keep the canonical `.env` at repo root: rejected because it blurs the root/app boundary the spec is trying to establish.
  - Duplicate app env files at root and app level: rejected because it creates split configuration truth.

## Decision 6

- **Decision**: Move app-specific tooling files with the app and leave repo-wide tooling configs at root.
- **Rationale**: `composer.json`, `package.json`, Vite, PHPUnit, and Drizzle are app-owned. Editor tasks, MCP config, agent config, docs, and Spec Kit files remain repo-owned.
- **Alternatives considered**:
  - Keep Drizzle or test config at root as a convenience: rejected unless a repo-wide consumer is proven, because it breaks the file-placement contract.

## Decision 7

- **Decision**: Treat repo documentation, MCP config, and agent instructions as first-class relocation work items, not post-move cleanup.
- **Rationale**: Current repo guidance is saturated with root-relative `vendor/bin/sail`, `artisan`, and `npm run` instructions. Leaving those untouched would undermine the single command model immediately after the move.
- **Alternatives considered**:
  - Update runtime only and defer docs or tooling: rejected because the spec explicitly includes DX and tooling alignment.

## Decision 8

- **Decision**: Capture Dokploy build context, production working directory, storage-volume assumptions, and unpublished helper scripts as explicit operational unknowns instead of silently designing around them.
- **Rationale**: These concerns cannot be proven from the repository alone, so the correct plan is to isolate them as rollout prerequisites rather than smuggling in guesses.
- **Alternatives considered**:
  - Assume staging and production behave like local Sail: rejected because the spec forbids hidden deploy assumptions.