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.