ahmido
03b1beb616
## Summary - add the first multi-app workspace foundation with a new standalone Astro website under `apps/website` - introduce repo-root pnpm workspace orchestration and migrate the platform Node workflow from npm assumptions to pnpm - update root docs, editor or agent guidance, and workspace-focused smoke tests for the new platform plus website command model - add Spec 183 artifacts for spec, plan, research, contracts, quickstart, checklist, and tasks ## Verification - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/WorkspaceFoundation` - `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` - `corepack pnpm build:website` - integrated-browser smoke: verified `http://localhost/up`, `http://localhost/admin/login`, and `http://localhost:4321/` including website anchor navigation and combined root dev flow ## Notes - branch: `183-website-workspace-foundation` - commit: `6d41618d` - root command model now covers `dev:platform`, `dev:website`, `dev`, `build:platform`, and `build:website` - website port override documentation is included in the command contract, quickstart, and README Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #214
86 lines
6.8 KiB
Markdown
86 lines
6.8 KiB
Markdown
# 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. |