# Data Model: Website Information Architecture / Core Pages

## Overview

This feature introduces no database schema. The model is a website-local route and discoverability contract expressed through page roles, navigation entries, publication rules, compatibility paths, and buyer-journey stages inside `apps/website`.

## Entities

### Website IA Contract

- **Purpose**: The canonical information-architecture contract for `apps/website`.
- **Key fields**:
  - `scope` (`apps/website` only)
  - `requiredCoreRoutes`
  - `recommendedCoreRoutes`
  - `optionalSurfaceFamilies`
  - `deferredSurfaceFamilies`
  - `primaryConversionRoute`
  - `legalBaselineRoutes`
  - `maxPrimaryInformationalLinks`
- **Relationships**:
  - Owns many `Public Surface` entries
  - Owns many `Navigation Entry` entries
  - Owns many `Footer Group` entries
  - Owns many `Content Publication Rule` entries
  - Owns many `Compatibility Path` entries
  - Owns many `Journey Stage` entries
- **Validation rules**:
  - Must remain explicitly local to `apps/website`
  - Must keep Trust top-level visible
  - Must keep one clear primary conversion route
  - Must keep primary navigation at or below 5 informational links plus one CTA
  - Must forbid placeholder or thin-content top-level surfaces

### Public Surface

- **Purpose**: A named public page or route that performs one clear job in the website journey.
- **Key fields**:
  - `path`
  - `role` (`home`, `product`, `trust`, `changelog`, `contact`, `privacy`, `imprint`, `secondary-supporting`, `secondary-legal`, `compatibility`)
  - `priority` (`required`, `recommended`, `optional`, `deferred`, `compatibility`)
  - `family` (`landing`, `trust`, `content`)
  - `jobStatement`
  - `buyerQuestionsAnswered`
  - `canonicalStatus` (`canonical`, `conditional`, `legacy`)
- **Relationships**:
  - Belongs to `Website IA Contract`
  - May appear in many `Navigation Entry` and `Footer Group` entries
  - May satisfy one or more `Journey Stage` entries
  - May be gated by one `Content Publication Rule`
- **Validation rules**:
  - Every required surface must have a named job in the buyer journey
  - Required surfaces must be publishable without relying on deferred surfaces
  - Optional surfaces cannot appear in primary navigation without passing content-readiness rules
  - Compatibility surfaces must never become a second canonical truth

### Navigation Entry

- **Purpose**: A visible public link in the header, footer, brand, or CTA slot.
- **Key fields**:
  - `location` (`brand`, `primary-nav`, `footer`, `primary-cta`, `secondary-cta`)
  - `label`
  - `href`
  - `prominence` (`informational`, `cta`, `legal`, `secondary`)
  - `visibilityRule`
  - `sourceSurfaceRole`
- **Relationships**:
  - Belongs to `Website IA Contract`
  - References one `Public Surface`
  - May belong to one `Footer Group`
- **Validation rules**:
  - Brand entry must route to `/`
  - Trust must have a visible `primary-nav` entry
  - Only one `primary-cta` route may be primary at a time
  - No `primary-nav` entry may point to a placeholder or deferred surface

### Footer Group

- **Purpose**: A semantic grouping of footer links that reinforces the public IA without inflating header navigation.
- **Key fields**:
  - `title`
  - `purpose` (`product`, `trust-legal`, `contact`, `content`)
  - `items`
- **Relationships**:
  - Belongs to `Website IA Contract`
  - Contains many `Navigation Entry` items
- **Validation rules**:
  - Footer must expose Product, Trust/Legal, and Contact discoverability
  - Privacy and Imprint must remain directly reachable from the footer
  - Content groups such as `Resources`, later editorial surfaces, or Docs may only appear when those surfaces are actually published

### Content Publication Rule

- **Purpose**: The rule that determines whether an optional public surface becomes discoverable.
- **Key fields**:
  - `surfaceFamily` (`resources`, `blog-editorial`, `docs`, `pricing`)
  - `contentSource`
  - `minimumSubstanceRule`
  - `primaryNavAllowed`
  - `footerAllowed`
  - `fallbackBehavior`
- **Relationships**:
  - Belongs to `Website IA Contract`
  - May gate one or more `Public Surface` entries
- **Validation rules**:
  - `Resources` may not be promoted until substantive content exists
  - The existing `articles` collection remains unpublished as `blog-editorial` inventory until a separate spec activates it
  - Docs and Pricing remain deferred until a later spec activates them
  - Changelog is exempt from optionality but still requires dated, substantive entries rather than an empty route

### Compatibility Path

- **Purpose**: A temporary or secondary path that preserves continuity during IA changes.
- **Key fields**:
  - `legacyPath`
  - `canonicalPath`
  - `strategy` (`redirect`, `secondary`, `retire`)
  - `reason`
  - `expiryIntent`
- **Relationships**:
  - Belongs to `Website IA Contract`
  - References one canonical `Public Surface`
- **Validation rules**:
  - Compatibility paths must not appear in primary navigation
  - Compatibility paths should not stay permanent without a separate justification
  - Sitemap and canonical-link generation must point to the canonical route, not the legacy alias

### Journey Stage

- **Purpose**: The required stage in the public buyer journey that the IA must support.
- **Key fields**:
  - `stage` (`entry`, `first-clarification`, `deepening`, `action`)
  - `primaryQuestion`
  - `allowedSurfaceRoles`
  - `requiredTransitions`
- **Relationships**:
  - Belongs to `Website IA Contract`
  - References many `Public Surface` roles
- **Validation rules**:
  - Entry surfaces must route visitors to Product, Trust, Changelog, or Contact without dead ends
  - Deepening surfaces must preserve a path to the primary conversion route
  - Outcome explanation must be present before or during the first-clarification stage, not deferred to a later optional hub

## Relationship Summary

- `Website IA Contract` owns many `Public Surface`
- `Website IA Contract` owns many `Navigation Entry`
- `Website IA Contract` owns many `Footer Group`
- `Website IA Contract` owns many `Content Publication Rule`
- `Website IA Contract` owns many `Compatibility Path`
- `Website IA Contract` owns many `Journey Stage`
- `Navigation Entry` references one `Public Surface`
- `Footer Group` contains many `Navigation Entry`
- `Content Publication Rule` gates one or more optional `Public Surface`
- `Compatibility Path` points to one canonical `Public Surface`
- `Journey Stage` is satisfied by one or more `Public Surface` roles

## State / Lifecycle Notes

- No persisted runtime state is introduced.
- The IA is repo-owned truth expressed through route files, route metadata, navigation config, and content publication decisions.
- A surface becomes public when its publication rules are satisfied and it is included in the canonical navigation/footer contract.
- Compatibility paths are transitional by design and should shrink over time rather than becoming a permanent parallel IA.