163 lines
6.8 KiB
Markdown
163 lines
6.8 KiB
Markdown
# 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. |