ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
201-enforcement-review-guardrails
TenantAtlas/docs/strategy/website-working-contract.md
ahmido 445464afdc
Some checks failed
Main Confidence / confidence (push) Failing after 46s
Details
docs: add website working contract (#247) 
## Summary
- add a repo-truth-based website working contract for `apps/website`
- link the new contract from the workspace README
- document the current minimal website/platform coordination boundaries

## Testing
- not run (documentation-only changes)

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #247
2026-04-18 14:17:46 +00:00

7.3 KiB
Raw Permalink Blame History

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.