old.cms.fellies.org/docs/product-engineering/critical-invariants.md

Critical Invariants

These rules must stay true across refactors and feature work.

Auth and User Invariants

• Exactly one owner user must exist.
• The canonical owner must remain protected and not banned.
• Support user is system-owned and protected.
• Protected users cannot be deleted through auth endpoints.
• First owner bootstrap closes open owner-registration window.

Primary implementation:

• apps/admin/src/lib/auth/server.ts
• apps/admin/src/app/api/auth/[...all]/route.ts

Primary tests:

• apps/admin/src/lib/auth/server.test.ts
• apps/admin/src/app/register/page.test.tsx
• apps/admin/src/app/welcome/page.test.tsx
• apps/admin/src/app/login/page.test.tsx

Registration Policy Invariants

• If no owner exists: welcome flow is open for first owner bootstrap.
• If owner exists: self-registration depends on persisted policy in system_setting.
• Register route must never silently create users when policy is disabled.

Primary implementation:

• packages/db/src/settings.ts
• apps/admin/src/app/settings/page.tsx
• apps/admin/src/app/register/page.tsx

Media Storage Contract

• Storage provider is selected by CMS_MEDIA_STORAGE_PROVIDER.
• S3 is primary; local is explicit fallback.
• Each media asset stores a stable storageKey.
• Deleting a media asset must also attempt storage object deletion.

Primary implementation:

• apps/admin/src/lib/media/storage.ts
• apps/admin/src/lib/media/storage-key.ts
• apps/admin/src/app/media/[id]/page.tsx

Public Rendering Contract

• Public pages must render only published CMS pages.
• Public navigation must be built from managed menu items.
• Header banner and announcements must be optional and fail-safe.

Primary implementation:

• apps/web/src/app/[locale]/layout.tsx
• apps/web/src/app/[locale]/page.tsx
• apps/web/src/app/[locale]/[slug]/page.tsx