TenantAtlas/specs/216-homepage-structure/data-model.md

# Data Model: Website Homepage Structure & Section Model

This feature introduces no database schema and no platform-side persistence. The model is file- and route-based inside `apps/website` and defines how the homepage composes required narrative blocks, proof signals, and route targets.

## 1. Homepage Composition

Represents the public homepage at `/` as one ordered narrative contract.

| Field | Type | Description | Rules |
|---|---|---|---|
| `path` | static string | Canonical homepage route | Must remain `/` |
| `seo` | `PageSeo` | Title, description, canonical path metadata | Required |
| `requiredBlocks` | ordered list | Functional homepage blocks | Must include header, hero, outcome, capability, trust, progress, CTA, footer |
| `primaryConversionTarget` | route | Dominant next-step route | Defaults to `/contact` until a distinct public `/demo` route exists |
| `secondaryRoutes` | route list | Deeper exploration targets | Limited to `/product`, `/trust`, `/changelog` |
| `optionalBlocks` | list | Supporting context such as ecosystem, FAQ, or use-case spotlight | May appear only if they do not displace required blocks |

**Relationships**:
- Composed from homepage content exports in `src/content/pages/home.ts`
- Uses canonical route/navigation truth from `src/lib/site.ts`
- May derive proof content from `src/content/pages/trust.ts` and the changelog collection

**Validation rules**:
- All required blocks must be present exactly once as functions, even if visually combined
- Trust and progress must appear before the lower-page CTA block
- Optional blocks must not replace or bury required blocks

## 2. Hero Block

Represents the first explanatory block on the homepage.

| Field | Type | Description | Rules |
|---|---|---|---|
| `eyebrow` | string | Short orienting label | Required |
| `title` | string | Positioning headline | Required |
| `description` | string | Supporting problem and product framing | Required |
| `primaryCta` | `CtaLink` | Main action from the hero | Exactly one primary CTA |
| `secondaryCta` | `CtaLink` | Deeper exploration route | At least one secondary deepening CTA on the homepage |
| `highlights` | string list | Short proof or focus points | Optional |
| `productVisual` | logical asset reference | Product-near screenshot or UI-adjacent visual | Must be product-near, not abstract-only |
| `trustSubclaims` | string list | Narrow supporting trust cues | Optional and only allowed when supportable by `/trust` |

**Validation rules**:
- Primary and secondary CTAs must not compete as equal primary actions
- Visual must communicate product truth or credible UI structure
- Trust subclaims cannot overstate compliance or hosting claims

## 3. Outcome Section

Explains why the product matters in buyer-oriented language.

| Field | Type | Description | Rules |
|---|---|---|---|
| `title` | string | Outcome framing headline | Required |
| `description` | string | Problem relevance and operational impact | Required |
| `outcomes` | item list | Buyer-visible improvements, frictions removed, or use-case outcomes | Required |
| `audienceBias` | label or note | Primary audience signal such as MSP, governance, or enterprise operations | Optional |

**Validation rules**:
- Must talk in outcomes, operational improvements, or frictions reduced
- Must not devolve into feature naming or route explanations

## 4. Capability Cluster

Represents grouped product-model coverage on the homepage.

| Field | Type | Description | Rules |
|---|---|---|---|
| `title` | string | Cluster title | Required |
| `description` | string | Short explanation of the cluster | Required |
| `capabilities` | string list | Covered product areas | Must express grouped capabilities, not one-card-per-feature sprawl |
| `href` | route | Deeper route for details | Normally `/product` |
| `meta` | string | Compact supporting label | Optional |

**Required coverage across all clusters**:
- Backup
- Restore
- Version history
- Auditability and evidence
- Inventory and drift visibility
- Governance, findings, exceptions, or review work

**Validation rules**:
- Clusters must create a readable hierarchy
- The homepage must explain the product model without acting as full documentation

## 5. Trust Signal Group

Represents the explicit homepage trust block.

| Field | Type | Description | Rules |
|---|---|---|---|
| `title` | string | Trust block heading | Required |
| `description` | string | Why trust matters on the homepage | Required |
| `signals` | `TrustPrincipleContent[]` or equivalent | Bounded trust principles or proof cards | Required |
| `supportRoute` | route | Deeper trust destination | Must be `/trust` |

**Validation rules**:
- Signals must be substantiated and bounded
- No invented badges, fake certifications, or sweeping compliance promises
- Must appear before the final CTA block

## 6. Progress Teaser

Represents visible product movement on the homepage.

| Field | Type | Description | Rules |
|---|---|---|---|
| `entries` | changelog entry list | Recent dated product updates | Derived from published changelog collection entries |
| `title` | string | Progress block title | Required |
| `description` | string | Explains why progress is shown | Required |
| `cta` | `CtaLink` | Route to full changelog | Must target `/changelog` |

**Validation rules**:
- Entries must be dated and publicly visible
- The block must feel factual, not like a marketing news feed

## 7. CTA Transition Block

Represents the lower-page call to action after clarity, trust, and progress have been established.

| Field | Type | Description | Rules |
|---|---|---|---|
| `title` | string | Final CTA heading | Required |
| `description` | string | What the next step is and why | Required |
| `primaryCta` | `CtaLink` | Dominant next-step action | Must target `/contact` or `/demo`; defaults to `/contact` today |
| `secondaryCta` | `CtaLink` | Optional deeper route | Must not compete as another primary action |

**Validation rules**:
- Must not introduce multiple equally strong primary conversion actions
- Must follow trust and progress blocks in the homepage order

## Derived State and Availability

- No independent state machine is added by this feature.
- Changelog teaser visibility is derived from the published changelog collection (`draft: false`).
- Optional route visibility remains derived from `getSurfaceAvailability()` and canonical route definitions in `src/lib/site.ts`.
- If a real screenshot is unavailable, hero visual readiness falls back to a credible UI-near visual, but the hero still must satisfy the product-near rule.