# Data Model: Platform Relocation to apps/platform

## Overview

This feature adds no new persisted database entities. The "model" for this slice is a set of logical relocation artifacts and validation rules that govern which files live where, how commands resolve the app, and how runtime integrity is proven after the move.

## Logical Entities

### RepoOrchestrationLayer

- **Purpose**: The repo-wide layer that remains at root after the move.
- **Fields**:
  - `root_directories`: `docs/`, `specs/`, `.specify/`, `scripts/`, `.github/`, `.vscode/`, and other repo metadata directories
  - `root_files`: `docker-compose.yml`, `README.md`, `Agents.md`, `GEMINI.md`, `boost.json`, `opencode.json`, repo ignore files, editor files
  - `ownership`: `repo-level`
- **Validation rules**:
  - Must not remain the authoritative home of `app/`, `bootstrap/`, `config/`, `database/`, `public/`, `resources/`, `routes/`, `storage/`, `tests/`, or app-local package manager files.
  - Any helper file kept at root must be explicitly classified as repo-level or compatibility-only.

### PlatformApplication

- **Purpose**: The relocated Laravel application living under `apps/platform`.
- **Fields**:
  - `app_root`: `apps/platform`
  - `runtime_directories`: `app/`, `bootstrap/`, `config/`, `database/`, `public/`, `resources/`, `routes/`, `storage/`, `tests/`
  - `runtime_files`: `artisan`, `composer.json`, `package.json`, `vite.config.js`, `phpunit.xml`, `phpunit.pgsql.xml`, `drizzle.config.ts`, `.env.example`
  - `ownership`: `application-level`
- **Validation rules**:
  - All authoritative Laravel runtime files must exist only under `apps/platform` after cutover.
  - Internal relative path assumptions should remain unchanged unless a boundary file proves otherwise.

### FilePlacementContract

- **Purpose**: The explicit matrix that defines what stays at root versus what moves into `apps/platform`.
- **Fields**:
  - `root_items`
  - `app_items`
  - `reviewed_exceptions`
  - `non_goals`
- **Validation rules**:
  - No reviewed exception may create a second authoritative app root.
  - Exception rationale must explain why root or app ownership is correct.

### CommandModel

- **Purpose**: The canonical developer workflow after relocation.
- **Fields**:
  - `canonical_working_directory`: `apps/platform`
  - `canonical_commands`: install, boot, build, test, format, and artisan examples
  - `compatibility_helpers`: optional root wrappers, tasks, or aliases that do nothing except delegate to the app root
  - `delegation_policy`: `compatibility-only`
- **Validation rules**:
  - Exactly one command model may be primary.
  - Any helper outside `apps/platform` must be clearly labeled non-canonical.

### EnvironmentModel

- **Purpose**: The configuration boundary between app config truth and compose-level wiring.
- **Fields**:
  - `app_env_path`: `apps/platform/.env`
  - `app_env_example_path`: `apps/platform/.env.example`
  - `compose_bridge_variable`: `SAIL_FILES`
  - `optional_root_compose_env`: compose-only variables if needed
- **Validation rules**:
  - Application `APP_*`, database, queue, cache, and other Laravel config truth must live with the app.
  - Root-level env data, if introduced, must not duplicate or override canonical app config truth except for explicit compose-only concerns.

### ComposeBridge

- **Purpose**: The boundary that lets repo-root compose orchestrate an app-local Laravel project.
- **Fields**:
  - `compose_file_path`: `docker-compose.yml`
  - `container_app_root`: `/var/www/html`
  - `mount_source`: `./apps/platform`
  - `sail_runtime_path`: `apps/platform/vendor/laravel/sail/runtimes/8.4`
  - `services`: `laravel.test`, `queue`, `pgsql`, `redis`
- **Validation rules**:
  - Web and queue services must execute against the relocated app root.
  - `node_modules` and storage-related container assumptions must resolve inside the relocated app.

### ToolingReference

- **Purpose**: A repo-level task, MCP, or agent configuration that launches platform commands.
- **Fields**:
  - `file_path`
  - `tool_type`: README, VS Code task, MCP config, agent instructions, automation script
  - `execution_mode`: direct app command or root delegator
  - `status`: stale, updated, deprecated
- **Validation rules**:
  - No maintained tooling reference may silently assume the app still lives at repo root.
  - Absolute local machine paths should be removed where reasonable during normalization.

### SmokeCheck

- **Purpose**: A required runtime or tooling validation step.
- **Fields**:
  - `id`
  - `area`: local boot, CLI, build, public entry, panel, auth, queue, tests, tooling
  - `command_or_route`
  - `expected_outcome`
  - `blocking`: yes or no
  - `evidence`
- **State transitions**:
  - `planned -> passed`
  - `planned -> failed`
  - `planned -> blocked`

### RollbackStep

- **Purpose**: A documented recovery action if the move must be reversed.
- **Fields**:
  - `order`
  - `scope`: git, env, dependencies, Docker, docs, open branches
  - `action`
  - `expected_result`
- **State transitions**:
  - `drafted -> verified`

### ExternalDeployUnknown

- **Purpose**: A deployment assumption that cannot be proven from the repo alone.
- **Fields**:
  - `question`
  - `why_unresolved`
  - `owner`
  - `required_before_rollout`: yes or no
  - `status`: open, validated, deferred
- **State transitions**:
  - `open -> validated`
  - `open -> deferred`

## Relationships

- `RepoOrchestrationLayer` owns `docker-compose.yml`, repo docs, editor config, MCP config, and agent config.
- `PlatformApplication` is the sole application runtime referenced by `CommandModel`, `EnvironmentModel`, and `ComposeBridge`.
- `FilePlacementContract` governs both `RepoOrchestrationLayer` and `PlatformApplication`.
- `ComposeBridge` links the repo-root compose layer to the app-local Laravel runtime.
- `ToolingReference` points either directly to `PlatformApplication` commands or to compatibility-only delegators.
- `SmokeCheck` validates `ComposeBridge`, `CommandModel`, `PlatformApplication`, and `ToolingReference` behavior after implementation.
- `RollbackStep` reverses changes across both root and app scopes.
- `ExternalDeployUnknown` captures rollout blockers that sit outside the repository implementation itself.

## Invariants

- There is exactly one authoritative Laravel app root after the move: `apps/platform`.
- There is exactly one official developer command model after the move: app-local commands from `apps/platform`.
- Repo root remains the orchestration and metadata layer, not a second application root.
- No new product persistence or runtime domain model is introduced by the relocation.