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.