# 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.