# 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 ` 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.