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