TenantAtlas/specs/182-platform-relocation/data-model.md

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.