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

Research: Website / Workspace Foundation

Decision 1: Use pnpm workspaces as the official JavaScript workspace standard

Decision: Adopt pnpm 10 workspaces with a root package.json and pnpm-workspace.yaml as the official JavaScript package-manager and workspace model for the repo.

Rationale:

• Spec 183 requires exactly one official workspace/package-manager standard.
• The repo currently has no root workspace manifest and only one tracked JavaScript package manifest under apps/platform, so the first multi-app slice needs an explicit root contract.
• pnpm workspaces require only a root pnpm-workspace.yaml and support a single shared lockfile, which keeps the first multi-app step narrow.
• Official pnpm workspace guidance confirms that workspaces are a built-in fit for multi-project repositories and that the root workspace file is the canonical entry point.
• The current environment already supports the migration path: host Node has Corepack available, and the running Sail container exposes both Corepack and pnpm.

Alternatives considered:

• Keep npm for apps/platform and introduce pnpm only for apps/website: rejected because it violates the spec's one-official-standard rule and creates an ambiguous dual model.
• Use npm workspaces: rejected because the spec's recommended direction is pnpm and pnpm offers the cleaner shared-lockfile monorepo path for this repo shape.
• Use Yarn or Bun workspaces: rejected because they add a new toolchain direction with no repo-specific advantage here.
• Introduce Turbo or Nx immediately: rejected as premature orchestration complexity for a two-app repo.

Decision 2: Use Astro as the website stack

Decision: Introduce apps/website as an Astro v6 application.

Rationale:

• The feature is explicitly a public website foundation, not a second authenticated product surface.
• Astro is designed for public-facing sites and supports the static-first model the spec asks for.
• Astro keeps the website runtime lightweight while avoiding accidental coupling to Blade, Filament, shared sessions, or Laravel panel assumptions.
• The docs emphasize project structure, dev/build flows, layouts, pages, and static-site friendly features, which align with this slice.

Alternatives considered:

• Build the website inside Laravel Blade: rejected because the spec explicitly forbids platform embedding and wants separate runtimes.
• Use another JavaScript SSR-heavy app shell such as Next.js or Nuxt: rejected because this slice does not need a heavier runtime or server coupling.
• Use a raw Vite-only site: rejected because Astro provides a clearer public-site application structure without forcing a custom content/runtime foundation.

Decision 3: Keep the platform Sail-first and do not Dockerize the website in V1

Decision: apps/platform remains the only Sail/Docker-backed application in this slice; apps/website runs as a plain Node application for local development and static builds.

Rationale:

• The current root docker-compose.yml and ./scripts/platform-sail wrapper are explicitly platform-specific and already stable.
• Dockerizing the website immediately would require a second service strategy, new port policy, and broader deployment assumptions that the spec does not require.
• The website does not need PostgreSQL, Redis, queues, or Laravel runtime services in this foundation slice.
• Keeping the website outside Sail preserves the root-orchestrates/apps-execute model while minimizing cross-app runtime coupling.

Alternatives considered:

• Add a second Docker Compose service for the website now: rejected as unnecessary orchestration growth in the first multi-app slice.
• Move both apps to host-only local dev: rejected because the platform is already Sail-first and that contract should remain stable.

Decision 4: Keep root orchestration thin and app-specific wrappers narrow

Decision: Add only thin root scripts for official entry points and keep ./scripts/platform-sail as a platform-only compatibility wrapper instead of generalizing it to a multi-app runner.

Rationale:

• The repo has one Sail-backed app today. A generic scripts/sail <app> wrapper would be an abstraction with only one concrete user.
• Spec 183 explicitly prefers minimal root orchestration and rejects premature shared layers or frameworkization.
• Root scripts can delegate to ./scripts/platform-sail for the platform and to pnpm --dir apps/website ... or workspace-filtered pnpm commands for the website without inventing a new app-runner subsystem.

Alternatives considered:

• Introduce a generalized app-launch wrapper immediately: rejected under ABSTR-001 because there is not yet real variance across multiple Docker-backed apps.
• Keep only app-local commands and document them: rejected because the spec requires an official root entry model.

Decision 5: Update only the tooling that now needs multi-app awareness

Decision: Update root docs, entry tasks, and agent/editor guidance to reflect the new workspace model, while keeping Laravel-specific MCP integration platform-only.

Rationale:

• .vscode/mcp.json and opencode.json currently point at the platform Boost MCP server only. That remains correct because the website is not a second Laravel runtime.
• The repo's tasks and docs currently assume only the platform exists. Those surfaces need new multi-app awareness so contributors understand the official entry path.
• A full task-system rewrite is not required to satisfy the spec. This slice only needs a clear, official root command surface and enough task/documentation updates to make it discoverable.

Alternatives considered:

• Add a second Boost MCP server for the website: rejected because the website app is not a Laravel app.
• Rename and rebuild every existing task in the repo: rejected because it is broader than the narrow workspace-foundation objective.

Decision 6: Build isolation matters more than early shared code reuse

Decision: Accept small duplication between apps/platform and apps/website, and do not introduce packages/, shared design tokens, or shared UI primitives in this slice.

Rationale:

• The current concrete problem is introducing a second app cleanly, not extracting shared code.
• A shared layer would force versioning, ownership, and build-coupling decisions before the repo has even demonstrated repeated needs across more than one new app.
• The spec explicitly states that duplication is acceptable in small amounts and that shared packages are a likely follow-up, not part of this slice.

Alternatives considered:

• Create packages/ui, packages/brand, or shared Tailwind tokens now: rejected as future-facing complexity without proven repeated use.
• Share platform assets or auth/session infrastructure with the website: rejected because the spec requires runtime separation.