148 lines
6.5 KiB
Markdown
148 lines
6.5 KiB
Markdown
# 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. |