104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# 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.
|