docs: add website working contract #247
@ -12,6 +12,9 @@ ## Multi-App Topology
|
|||||||
- repo root: workspace manifests, documentation, scripts, editor tooling, and `docker-compose.yml`
|
- 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`
|
- `./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
|
## Official Root Commands
|
||||||
|
|
||||||
- Install workspace-managed JavaScript dependencies: `corepack pnpm install`
|
- Install workspace-managed JavaScript dependencies: `corepack pnpm install`
|
||||||
|
|||||||
237
docs/strategy/website-working-contract.md
Normal file
237
docs/strategy/website-working-contract.md
Normal file
@ -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.
|
||||||
Loading…
Reference in New Issue
Block a user