TenantAtlas/specs/183-website-workspace-foundation/plan.md

Implementation Plan: Website / Workspace Foundation

Branch: 183-website-workspace-foundation | Date: 2026-04-08 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/183-website-workspace-foundation/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/183-website-workspace-foundation/spec.md and repo-context planning for the first real multi-app workspace slice.

Summary

Introduce the first true multi-app foundation by adding a public website application under apps/website while keeping the existing Laravel platform stable under apps/platform. The implementation uses a minimal root orchestration model: one official Node workspace standard at repo root, one static-first website runtime, thin root scripts that orchestrate instead of re-implementing app logic, and a clear split between repo-level metadata, website runtime concerns, and platform runtime concerns.

Key approach: adopt pnpm workspaces as the official root package-manager standard, initialize the public website as an Astro app under apps/website, migrate the platform's Node command surface from npm to pnpm so the repo has one official JavaScript package-manager model, keep the platform Sail-first and Docker-backed, keep the website outside Sail in this first slice, and update only the root docs, tooling, and tasks that need multi-app awareness. The plan explicitly avoids shared packages, Turbo or Nx, a docs app, a customer app, a generalized app-runner framework, or any new TenantPilot product behavior.

The feature leaves Filament v5 on Livewire v4 unchanged, keeps panel providers registered in apps/platform/bootstrap/providers.php, does not add or alter globally searchable resources, introduces no destructive operator actions, and preserves the existing deploy-time cd apps/platform && php artisan filament:assets responsibility for platform assets.

Technical Context

Language/Version: PHP 8.4.15 and Laravel 12 for apps/platform; Node.js 20+ with pnpm 10 workspace tooling; Astro v6 for apps/website; Bash and Docker Compose for root orchestration
Primary Dependencies: laravel/framework, filament/filament, livewire/livewire, laravel/sail, vite, tailwindcss, pnpm workspaces, Astro, existing ./scripts/platform-sail wrapper, repo-root Docker Compose
Storage: Existing PostgreSQL, Redis, and filesystem storage for apps/platform; static build artifacts for apps/website; repository-managed workspace manifests and docs; no new database persistence
Testing: Existing Pest v4 platform tests through Sail; website boot/build smoke; root command smoke; parallel-run and build-isolation validation; targeted task and MCP smoke where tooling changes
Target Platform: macOS and Linux developer machines, Dockerized Laravel platform runtime, Node-based static public website runtime, Dokploy-style container deployment for the platform and static-site deployment for the website Project Type: Multi-app repo with repo-root orchestration, one Laravel platform app, and one static-first public website app
Performance Goals: Preserve current platform boot/build behavior; keep website dev/build lightweight; allow platform and website to run in parallel on distinct ports with no cross-app artifact pollution
Constraints: One official workspace standard only; no shared packages; no docs/customer/API surfaces; no website embedding into Blade or Filament; no root-level monorepo framework; keep platform Sail-first; root orchestrates while apps execute
Scale/Scope: Two first-class applications under apps/, root orchestration manifests and scripts, documentation and task updates, and smoke validation across local boot, coexistence, and build separation

Constitution Check

GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.

Principle	Status	Notes
Inventory-first	Pass	No inventory, snapshot, or backup truth changes; this is repo topology and runtime orchestration only
Read/write separation	Pass	No new product mutation flow, operator write surface, or external write behavior is introduced
Graph contract path	Pass	No Microsoft Graph calls or contract-registry changes are in scope
Deterministic capabilities	Pass	Capability derivation and registries remain unchanged
RBAC-UX planes and 404 vs 403	Pass	/admin, /admin/t/{tenant}/..., and /system authorization semantics remain unchanged
Workspace isolation	Pass	No new workspace-scoped data access or workspace routing behavior is introduced
Tenant isolation	Pass	No tenant-owned routes, queries, or UI semantics are broadened
Global search safety	Pass	No resource or global-search behavior changes are planned
Dangerous and destructive confirmations	Pass	No new destructive operator actions are introduced
Run observability	Pass	No new long-running product operations or OperationRun flows are introduced
Ops-UX 3-surface feedback	Pass	Not applicable because no operation UX is added or changed
Data minimization	Pass	No new secrets, logs, payload mirrors, or persisted product truth are added
Proportionality (PROP-001)	Pass	The design adds only one website app and the minimum root orchestration needed to support it
No premature abstraction (ABSTR-001)	Pass	The plan explicitly rejects Turbo, Nx, packages, a generic app-runner wrapper, and a generalized Sail abstraction
Persisted truth (PERSIST-001)	Pass	Only repository artifacts are added; no new application tables or persisted domain entities
Behavioral state (STATE-001)	Pass	No new domain status or reason-code family is introduced
UI semantics (UI-SEM-001)	Pass	No new operator semantic layer is introduced; the website is a separate public app
Filament-native UI (UI-FIL-001)	Pass	Platform Filament surfaces stay unchanged
Filament v5 / Livewire v4 compliance	Pass	Platform remains on Filament v5 with Livewire v4; the website app does not affect that stack
Provider registration location	Pass	Provider registration remains in apps/platform/bootstrap/providers.php
Global search hard rule	Pass	No globally searchable resource gains or losses are introduced
Asset strategy	Pass	Platform assets remain app-local and keep the filament:assets deploy step; website assets build independently from apps/website
Testing plan	Pass	The plan includes platform regression smoke, website boot/build smoke, root command smoke, and coexistence validation

Phase 0 Research

Research outcomes are captured in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/183-website-workspace-foundation/research.md.

Key decisions:

• Adopt pnpm workspaces as the official JavaScript package-manager standard for the multi-app repo. The root receives package.json plus pnpm-workspace.yaml, and the platform's Node command surface migrates from npm to pnpm so the repo has one official package-manager story.
• Use Astro v6 as the website stack because the spec explicitly wants a public-surface, static-first foundation with minimal runtime coupling.
• Keep the platform Sail-first and Docker-backed, but do not Dockerize the website in this first slice. The website should run as a plain Node app to keep the first multi-app step proportional.
• Keep ./scripts/platform-sail as a platform-only compatibility helper. Do not introduce a generic scripts/sail <app> abstraction because only one app uses Sail today.
• Keep Boost MCP and Laravel-specific editor integration platform-only. The website app is not a second Laravel runtime in this slice, so .vscode/mcp.json and opencode.json only need clearer scoping, not a second Boost server.
• Limit root task updates to the official entry tasks and any affected labels or notes. This slice does not justify a wholesale task-system rewrite.

Phase 1 Design

Design artifacts are created under /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/183-website-workspace-foundation/:

• data-model.md: repository-artifact and runtime-boundary model for root orchestration, platform app, website app, and tooling surfaces
• contracts/workspace-command-model.md: canonical root and app-local command contract for platform, website, and parallel local development
• contracts/coexistence-smoke.openapi.yaml: HTTP and orchestration smoke contract for website/platform coexistence
• quickstart.md: implementation, validation, and rollout checklist for the workspace foundation

Design decisions:

• The root owns JavaScript workspace orchestration, but PHP and Laravel runtime ownership stays inside apps/platform.
• The official root command model is intentionally small: install workspace dependencies, start the platform, start the website, start both, build the website, and build platform frontend assets.
• The platform retains its current Docker Compose topology and ./scripts/platform-sail wrapper. The website does not join Docker Compose in this slice.
• The root does not introduce packages/, shared tokens, shared components, or cross-app runtime modules.
• Root documentation and tooling are updated only where multi-app awareness is now necessary: README, Agents/GEMINI/Copilot guidance, entry tasks, and root-level config that references the platform as the only app.

Project Structure

Documentation (this feature)

specs/183-website-workspace-foundation/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── workspace-command-model.md
│   └── coexistence-smoke.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md

Source Code (repository root)

repo-root/
├── apps/
│   ├── platform/
│   │   ├── app/
│   │   ├── bootstrap/
│   │   ├── config/
│   │   ├── database/
│   │   ├── public/
│   │   ├── resources/
│   │   ├── routes/
│   │   ├── storage/
│   │   ├── tests/
│   │   ├── artisan
│   │   ├── composer.json
│   │   ├── package.json
│   │   └── vite.config.js
│   └── website/
│       ├── package.json
│       ├── astro.config.mjs
│       ├── public/
│       └── src/
├── docs/
├── specs/
├── scripts/
├── .specify/
├── .github/
├── .vscode/
├── docker-compose.yml
├── package.json
├── pnpm-workspace.yaml
├── README.md
├── Agents.md
├── GEMINI.md
├── boost.json
└── opencode.json

Structure Decision: Repo-root workspace orchestration plus two app roots under apps/: the existing Laravel platform and a new Astro website. No packages/ layer, no docs app, and no generalized monorepo framework are introduced.

Implementation Strategy

Phase A — Establish The Official Root Workspace Standard

Goal: Make the repo root the canonical JavaScript workspace entry point without turning it into an application runtime.

Step	Area	Change
A.1	Workspace manifests	Add a minimal root package.json and pnpm-workspace.yaml for apps/*
A.2	Package-manager contract	Declare pnpm as the official JS package-manager standard and remove the implicit npm-only assumption from root docs and tooling
A.3	Lockfile model	Replace per-app package-lock.json usage for maintained app packages with one root pnpm-lock.yaml
A.4	Root scripts	Define thin root scripts for platform start, website start, parallel dev, website build, and platform frontend build

Phase B — Align The Platform App With The Workspace Standard

Goal: Keep apps/platform stable while letting it participate in the official pnpm-based workspace model.

Step	Area	Change
B.1	Platform package manifest	Update apps/platform/package.json scripts to work under pnpm instead of npm-only assumptions
B.2	Composer scripts	Adjust apps/platform/composer.json Node-invoking scripts from npm to pnpm where they are part of the supported workflow
B.3	Sail runtime path	Keep ./scripts/platform-sail and existing Compose wiring; rely on Corepack/pnpm availability inside Sail instead of building a new orchestration wrapper
B.4	Asset isolation	Preserve platform asset outputs under apps/platform/public/build and keep deploy-time php artisan filament:assets unchanged

Phase C — Create The Website App As A Separate Public Runtime

Goal: Introduce apps/website as a real standalone app with its own dev and build lifecycle.

Step	Area	Change
C.1	Website scaffold	Create apps/website with Astro config, package manifest, src/, and public/
C.2	Public pages	Add the narrow initial public site structure needed for the foundation slice, without CMS/blog/docs/customer scope
C.3	Dev/build scripts	Ensure website dev and build commands run from root orchestration and app-local commands alike
C.4	Runtime separation	Keep website ports, environment assumptions, and build output isolated from the platform app

Phase D — Update Root Orchestration, Tooling, And Docs

Goal: Make the repo entry path obvious and keep automation aligned with the new topology.

Step	Area	Change
D.1	README and architecture notes	Document the multi-app topology, official command model, and app-local ownership clearly
D.2	Agent and editor guidance	Update Agents.md, GEMINI.md, .github/copilot-instructions.md, and related guidance where root multi-app knowledge now matters
D.3	VS Code and root tooling	Add or adjust official entry tasks for platform, website, and parallel dev; keep Boost MCP platform-only but document that scope explicitly
D.4	Ignore and repo hygiene	Update ignore files and related repo metadata for apps/website, root lockfiles, and website build artifacts

Phase E — Validate Coexistence And Build Separation

Goal: Prove the multi-app repo behaves coherently before implementation is considered complete.

Step	Area	Change
E.1	Platform stability	Verify existing platform boot paths and focused regression tests still pass
E.2	Website boot	Verify the website starts independently and is reachable on its own dev port
E.3	Parallel dev	Verify the platform and website can run together without port or artifact collisions
E.4	Build separation	Verify website build outputs remain isolated and platform frontend build still works independently
E.5	Documentation usability	Verify a contributor can follow the updated root entry docs without hidden steps

Key Design Decisions

D-001 — pnpm Becomes The One Official JavaScript Workspace Standard

The repo currently has only apps/platform/package.json plus a tracked package-lock.json, but Spec 183 requires one clear workspace/package-manager standard. pnpm workspaces give the minimal root construct needed for multi-app orchestration without requiring a heavier monorepo framework.

D-002 — The Website Is A Static-First Astro App, Not A Second Laravel Runtime

The spec calls for a public website foundation, not another back-office application. Astro fits the static-first, public-surface constraint and avoids accidental coupling to platform sessions, Blade, Filament, or Laravel-specific runtime assumptions.

D-003 — The Platform Stays Sail-First; The Website Does Not Join Docker In V1

The current Compose file and wrapper are already platform-specific and stable. Dockerizing the website now would add extra service orchestration, port strategy, and deployment assumptions that the spec explicitly tries to avoid in the first slice.

D-004 — Root Scripts Orchestrate; App Logic Stays In The Apps

The root will provide the official entry scripts, but the platform keeps its app-local Sail and Composer logic, and the website keeps its app-local Astro logic. Root scripts are thin delegators, not a new orchestration framework.

D-005 — No Shared Packages Or Generic App Wrappers In This Slice

This slice deliberately rejects packages/, shared token libraries, a generalized scripts/sail <app> abstraction, Turbo, Nx, and any cross-app build framework. Those additions would solve hypothetical future variance rather than the current concrete need.

Risk Assessment

Risk	Impact	Likelihood	Mitigation
pnpm migration breaks existing platform frontend commands or Composer scripts	High	Medium	Update platform package.json and composer.json together, and verify pnpm inside Sail before relying on it
Contributors confuse root commands, app-local commands, and compatibility helpers	High	Medium	Publish one root command contract and keep app-local commands documented as secondary but valid
Website dev port collides with current platform or Vite usage	Medium	Medium	Reserve a distinct website port and document override rules in quickstart and root scripts
Root tooling remains platform-only in ways that confuse contributors after website arrives	Medium	High	Update README, task entry points, and agent guidance in the same slice as the website introduction
The slice drifts into packages, shared tokens, or a docs app	High	Medium	Treat all extra surfaces and packages as explicit non-goals and block them in review
Deployment assumptions for the website are overbuilt too early	Medium	Medium	Keep website deployment guidance minimal and static-site oriented, separate from the platform's Dokploy flow

Test Strategy

• Keep platform regression coverage focused: run the minimum representative Sail-driven Pest tests that prove the platform remains stable after the workspace changes.
• Validate platform boot via existing local health and login surfaces such as /up and /admin/login after root/workspace changes land.
• Validate website boot independently on its own dev server and verify it remains reachable without the platform app running.
• Validate root entry commands for website-only, platform-only, and combined local development flows.
• Validate platform frontend build and website build independently, ensuring outputs remain in their app-local directories.
• Validate at least one affected VS Code task or root tooling entry path so editor automation does not drift behind the repo topology.
• Reconfirm Filament v5 and Livewire v4 compliance by leaving the platform stack untouched and ensuring provider registration remains in apps/platform/bootstrap/providers.php.
• Preserve the platform asset deployment contract by keeping cd apps/platform && php artisan filament:assets in deployment guidance.

Complexity Tracking

No constitution violation or exemption is planned. The feature intentionally limits complexity to one new app plus the minimum workspace contract needed to support it.

Proportionality Review

• Current operator problem: The repo needs a public website surface now, but still behaves operationally like a single-app workspace. That makes local setup, docs, and tooling inconsistent the moment a second app is added.
• Existing structure is insufficient because: apps/platform is correctly isolated, but the repo root still lacks a real workspace standard, root command model, and second-app boundary.
• Narrowest correct implementation: Add one website app, one official root workspace standard, a thin root orchestration layer, and only the documentation and tooling updates required to make that structure usable.
• Ownership cost created: One additional app lifecycle, one shared JS workspace lockfile, root script maintenance, and multi-app smoke validation.
• Alternative intentionally rejected: Embedding the website into Laravel, keeping npm for the platform while adding pnpm only for the website, or introducing shared packages and monorepo frameworks immediately. Each alternative either violates the one-standard rule or adds speculative complexity.
• Release truth: Current-release infrastructure truth for the first public website surface, not future-only preparation.