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

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.

6.8 KiB Raw Blame History