diff --git a/README.md b/README.md index c45abac6..c77a071c 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,9 @@ ## Multi-App Topology - repo root: workspace manifests, documentation, scripts, editor tooling, and `docker-compose.yml` - `./scripts/platform-sail`: platform-only compatibility helper for tooling that cannot set `cwd` +Website-track guardrails for independent evolution live in +[`docs/strategy/website-working-contract.md`](docs/strategy/website-working-contract.md). + ## Official Root Commands - Install workspace-managed JavaScript dependencies: `corepack pnpm install` diff --git a/docs/strategy/website-working-contract.md b/docs/strategy/website-working-contract.md new file mode 100644 index 00000000..5166933d --- /dev/null +++ b/docs/strategy/website-working-contract.md @@ -0,0 +1,237 @@ +# 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. \ No newline at end of file