TenantAtlas/specs/226-astrodeck-inventory-planning/data-model.md

Data Model: AstroDeck Inventory Planning (Website)

Overview

This feature introduces no database schema. The model defines planning artifacts that describe AstroDeck primitive availability in apps/website.

Entities

InventoryCatalog

• Purpose: Canonical inventory container for one website planning baseline.
• Fields:
  • catalog_id (string, format: astrodeck-v<YYYY-MM-DD>, e.g. astrodeck-v2026-04-22; use astrodeck-226-baseline for the first Spec 226 catalog)
  • scope (fixed: apps/website)
  • created_at (ISO datetime)
  • source_commit (git SHA or reference)
  • status (draft, reviewed, baselined)
• Relationships:
  • Has many InventoryEntry
  • Has one SuitabilitySummary
• Validation rules:
  • Must include entries for all three primitive classes.
  • Cannot reach baselined unless every entry has required attributes and suitability.

InventoryEntry

• Purpose: One documented AstroDeck primitive candidate.
• Fields:
  • entry_id (string, unique within catalog)
  • identifier (human-readable or technical name)
  • primitive_class (Page, Section, Component)
  • file_ref (workspace-relative path)
  • functional_role (string)
  • default_semantics (string)
  • default_visual_character (closed enum: minimal | enterprise-neutral | content-heavy | bold-visual | utility-dense | decorative; add notes for anything outside this set)
  • tenantatlas_relevance (high, medium, low, none)
  • suitability_class (A, B, C, D)
  • markers (string array)
  • notes (optional string)
• Relationships:
  • Belongs to InventoryCatalog
• Validation rules:
  • Required core fields must be non-empty.
  • primitive_class and suitability_class values are constrained.
  • markers must come from allowed marker vocabulary.

SuitabilitySummary

• Purpose: Aggregated view of candidate distribution and risk visibility.
• Fields:
  • count_a, count_b, count_c, count_d (integers)
  • risk_visual_count (integer)
  • risk_semantic_count (integer)
  • demo_only_count (integer)
  • surface_candidates (object keyed by surface: homepage, hero, product, trust, changelog, contact-demo, navigation, footer)
• Relationships:
  • Belongs to InventoryCatalog
• Validation rules:
  • Aggregate counts must reconcile with InventoryEntry rows.
  • Every required surface key must be present.

MarkerVocabulary

• Purpose: Allowed marker set for consistent tagging.
• Allowed values:
  • tenantatlas-likely
  • needs-heavy-adaptation
  • visual-risk
  • semantic-risk
  • demo-only
  • remove-likely
  • hero-candidate
  • trust-candidate
  • navigation-candidate
  • footer-candidate
  • contact-candidate
  • product-explainer-candidate
  • changelog-candidate

Primitive Class Mapping

• Page — route entrypoints in apps/website/src/pages/
• Section — composite sections in apps/website/src/components/sections/
• Component — all reusable units across three sub-families:
  • primitives/ (structural atoms)
  • content/ (semantic content blocks)
  • layout/ (shell, navigation, footer) — layout/ maps to primitive_class: Component; there is no fourth primitive class

Lifecycle

Catalog Status Transitions

• draft -> reviewed
  • Condition: required fields complete and class coverage verified.
• reviewed -> baselined
  • Condition: suitability summary reconciled and candidate/risk visibility confirmed.
• baselined -> draft
  • Condition: source primitive set changes and inventory requires refresh.

Derived Rules

• No mapping spec may claim candidate selection without referencing entry_id from the active baselined catalog.
• Non-candidates (D) remain first-class records and cannot be hidden from summary outputs.