# Website Working Contract > Guardrails for evolving `apps/website` as an independently evolvable track in the current repository. > This document is repo-truth-based and describes the currently verified state, not a speculative future architecture. **Last reviewed**: 2026-04-18 --- ## 1. Purpose `apps/website` is currently treated as an independently evolvable website track. This contract is based on the current repository state: - no verified runtime coupling to `apps/platform` - no verified shared DTO, enum, API, or auth contracts - current relevant coupling is primarily through root scripts, the pnpm workspace, the website package name, `WEBSITE_PORT`, and `apps/platform/tests/Feature/WorkspaceFoundation/PlatformWorkspaceCompatibilityTest.php` Therefore, website work should be planned and implemented as technically independent by default unless a known minimal contract is being changed. ## 2. Scope This working contract applies to: - `apps/website/**` - root files only insofar as they directly define or preserve website-facing workspace contracts This document does not grant implicit approval to introduce new coupling to: - `apps/platform` - shared runtime APIs - shared auth or session behavior - shared domain models - shared packages Such coupling must be introduced deliberately and treated as a new explicit contract. ## 3. Current Repo-Based Statement At the current verified repo state, `apps/website` is: - a small static Astro application - built from local layout, local page, and local CSS files - without verified platform runtime dependency - without verified shared workspace packages - without verified platform API usage - without verified auth or session sharing The current real technical coupling is concentrated in: - `package.json` - `pnpm-workspace.yaml` - `apps/website/package.json` - `README.md` - `apps/platform/tests/Feature/WorkspaceFoundation/PlatformWorkspaceCompatibilityTest.php` ## 4. Freely Changeable Without Special Coordination The following changes are currently treated as website-internal and are generally free to make as long as they do not create new outward-facing contracts. ### Content and Structure - copy - headlines - messaging - CTA text - page sections - HTML structure inside the website ### UI and Frontend - styling in `src/styles/global.css` - layout changes in `src/layouts/BaseLayout.astro` - additional components inside `apps/website` - additional pages under `src/pages` - additional layouts - additional local assets ### Astro-Local Evolution - expanding page structure - refactoring inline markup into components - app-local reorganization inside `apps/website` - local SEO, meta, robots, and favicon updates ### Usually Non-Critical When Kept Local - new website-only dependencies - app-local build or styling improvements - app-local content structures ## 5. Changes Requiring Coordination The following changes must not happen silently because they touch real existing contracts in the current repository. ### Hard Minimal Contracts - changing the package name `@tenantatlas/website` - changing the root script names for website flows - changing the `WEBSITE_PORT` convention - changing workspace membership via `apps/*` - moving `apps/website` out of the current workspace pattern ### Repo and Tooling Contracts - changes that break `pnpm --filter @tenantatlas/website ...` - changes that break the root `dev:website` or `build:website` workflows - changes that break `PlatformWorkspaceCompatibilityTest.php` - changes to root scripts when the website is expected to remain reachable through root commands ### New Technical Couplings - introducing API calls to `apps/platform` - introducing shared DTOs, enums, or payload contracts - introducing shared auth or session mechanics - introducing shared packages as a required dependency - introducing shared content or asset sources - introducing a shared runtime deployment model ## 6. Silent Assumptions That Are Not Allowed For website work, the following assumptions are explicitly disallowed: - monorepo membership does not automatically mean technical coupling - `apps/platform` is not automatically part of website frontend scope - Filament or Livewire changes are not automatically website-relevant - shared product domain does not automatically imply a shared technical contract - future integrations must not be pre-assumed when they do not exist in the repo ## 7. Rule for New Couplings New coupling between website and platform is allowed only when it is introduced as an explicit new contract. Before implementation, the following must be made clear: - which coupling is being introduced - where it is defined in the repo - whether it is runtime, build, deploy, or convention coupling - what impact it has on independent evolution of `apps/website` - what stability guarantee is expected going forward Without that explicit decision, the default rule is: **Do not introduce a new coupling.** ## 8. Review Rule for Website PRs A change in `apps/website` is uncritical by default when all of the following can be answered with `Yes`: - Does the package name `@tenantatlas/website` remain unchanged? - Do the root scripts remain functionally compatible? - Does `WEBSITE_PORT` remain unchanged? - Does workspace membership through `apps/*` remain intact? - Is no new dependency on `apps/platform` introduced? - Is no new API, auth, DTO, or shared-package contract introduced? - Does the change stay entirely inside `apps/website`? If any answer is `No`, the change is coordination-required. ## 9. Change Classes ### Class A — Free Pure website change with no new outward-facing contract. Examples: - new landing page - refactor of `index.astro` - new components - CSS restructuring - local SEO changes ### Class B — Cautious Change likely remains local but touches website build or dev behavior. Examples: - adjusting Astro configuration - adding website dependencies - larger structural changes in `src/` Normal website review is usually sufficient. ### Class C — Coordination-Required Change touches root, workspace, or test contracts, or introduces new coupling. Examples: - renaming the package - changing scripts - changing the port convention - changing the workspace pattern - integrating a platform API - introducing shared types These changes require explicit coordination. ## 10. Operational Summary Yes: `apps/website` may currently be developed as its own frontend and website track. Condition: the known minimal contracts stay stable: - `@tenantatlas/website` - root scripts - `WEBSITE_PORT` - `apps/*` - compatibility with `PlatformWorkspaceCompatibilityTest.php` Not automatically part of website scope: - changes in `apps/platform` Introduce only deliberately: - any new runtime, API, auth, shared-package, or DTO coupling ## 11. Evidence Anchors This contract is grounded in the current repo state represented by these files: - `apps/website/package.json` - `apps/website/astro.config.mjs` - `apps/website/src/pages/index.astro` - `apps/website/src/layouts/BaseLayout.astro` - `apps/website/src/styles/global.css` - `package.json` - `pnpm-workspace.yaml` - `README.md` - `apps/platform/tests/Feature/WorkspaceFoundation/PlatformWorkspaceCompatibilityTest.php` - `docker-compose.yml` If these files change materially, this contract should be revalidated against the current checkout.