docs: add website working contract
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 51s
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 51s
This commit is contained in:
Ahmed Darrazi
parent
ea9ef9cb38
commit
1e5ddc9be5
@ -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`
|
||||
|
||||
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