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.

6.5 KiB Raw Blame History