TenantAtlas/specs/223-astrodeck-website-rebuild/data-model.md

Data Model: Website Reset and AstroDeck Rebuild

This feature does not introduce runtime persistence. The entities below define the planning artifacts that must exist for the rebuild workflow to remain reviewable and deterministic.

Entity: LegacyWebsiteImplementation

• Purpose: Represents the current apps/website codebase as the retired implementation substrate.
• Fields:
  • scopePath: repository path being retired, currently apps/website
  • status: discarded implementation history
  • replacedBySpec: spec reference that formally retires it, 223-astrodeck-website-rebuild
  • notes: short rationale for why it is no longer the active base
• Relationships:
  • One LegacyWebsiteImplementation has many LegacyTaskDisposition records.

Entity: CurrentWebsiteSurface

• Purpose: Captures the existing public routes and current website surfaces that must be reconciled during rebuild planning.
• Fields:
  • route: public route, such as /, /product, /trust, /contact, /legal
  • sourceFile: current Astro page file
  • surfaceRole: current role in the website IA, such as core, secondary, legal, redirect, or optional
  • governingSpecs: list of active website specs that currently constrain the surface
  • currentDependencies: content collections, layout primitives, tests, or redirects tied to the surface
  • plannedDisposition: keep, adapt, remove, or redirect
• Relationships:
  • A CurrentWebsiteSurface may map to one or more AstroDeckPrimitive candidates through PrimitiveMapping.

Entity: AstroDeckSourceIntake

• Purpose: Captures the reviewable AstroDeck source snapshot, intake constraints, and working assumptions before primitive mapping begins.
• Fields:
  • sourceSnapshotReference: path, tag, archive name, or other stable reference for the imported AstroDeck source
  • intakeConstraints: list of intake limitations, licensing boundaries, or review constraints
  • reviewAssumptions: explicit assumptions used while building the primitive inventory and mappings
  • notes: traceability details for reviewers
• Relationships:
  • One AstroDeckSourceIntake may inform many AstroDeckPrimitive records.

Entity: GoverningWebsiteSpec

• Purpose: Tracks each existing website spec that must be classified before rebuild work continues.
• Fields:
  • specId: current spec number, initially one of 213, 214, 215, 217, 218
  • title: short spec title
  • classification: continuing, partially valid, or superseded
  • scopeSummary: what part of the website the spec governs
  • followUpPlan: reference to the per-spec mapping artifact or explicit supersession-closure artifact that owns current-slice delivery for this spec
  • rationale: why the classification was chosen
• Relationships:
  • One GoverningWebsiteSpec has many PrimitiveMapping records.
  • One GoverningWebsiteSpec has many LegacyTaskDisposition records.
  • One GoverningWebsiteSpec may have one SupersessionClosure when rebuild planning ends with an explicit closure instead of a mapping plan.

Entity: SupersessionClosure

• Purpose: Captures the explicit closure artifact used when an in-scope website spec is classified as superseded and therefore does not continue into a mapping-based rebuild plan.
• Fields:
  • specId: governing website spec being closed out
  • classification: superseded
  • closureRationale: why the spec no longer needs a rebuild mapping artifact
  • legacyTaskDispositionReference: where the superseded legacy tasks were recorded
  • replacementReference: replacement plan reference or explicit no replacement work required statement
  • notes: traceability details for reviewers
• Relationships:
  • One SupersessionClosure belongs to one GoverningWebsiteSpec.

Entity: AstroDeckPrimitive

• Purpose: Represents a candidate AstroDeck page, section, or component available for rebuild mapping.
• Fields:
  • primitiveId: stable identifier inside the imported AstroDeck inventory
  • primitiveType: page, section, or component
  • sourceReference: where the primitive came from inside the AstroDeck source snapshot
  • candidateSurfaces: current routes or spec requirements it may satisfy
  • demoContentFlags: whether it carries demo copy, demo media, or demo CTA behavior that may require removal
  • notes: freeform adaptation concerns
• Relationships:
  • One AstroDeckPrimitive may be referenced by many PrimitiveMapping records.

Entity: PrimitiveMapping

• Purpose: Records how a governing website spec requirement maps to one AstroDeck primitive or falls through to a documented missing-candidate exception path, including the replacement task ownership captured inside the same per-spec artifact.
• Fields:
  • specId: owning website spec
  • requirementReference: spec requirement, acceptance point, or surface requirement being mapped
  • primitiveId: referenced AstroDeck primitive when a concrete candidate exists; omitted when the disposition is exception
  • disposition: keep, adapt, remove, or exception
  • adaptationSummary: required changes to route, structure, styling, copy slots, or CTA behavior
  • acceptanceMapping: how the mapped primitive satisfies the spec once adapted
  • replacementTasks: ordered replacement task list owned by the same per-spec mapping or disposition artifact
  • taskPrimitiveReferences: named AstroDeck pages, sections, components, or explicit mapping activities referenced by the replacement task list
  • materialDriftReferences: references to updated or follow-up website specs required when AstroDeck adoption changes page inventory, CTA logic, navigation, or trust messaging
  • exceptionReference: linked DocumentedException record when the disposition is exception
• Relationships:
  • Many PrimitiveMapping records belong to one GoverningWebsiteSpec.
  • Many PrimitiveMapping records may target one AstroDeckPrimitive.
  • One PrimitiveMapping may have zero or one DocumentedException.

Entity: ExceptionRegisterEntry

• Purpose: Captures the review outcome for each missing-candidate check so the rebuild keeps a standing register of approved exceptions and explicit no-exception outcomes.
• Fields:
  • specId: governing website spec under review
  • scope: page, section, component, or route slice being checked
  • reviewOutcome: approved exception or no exception required
  • reviewRationale: why the review produced that outcome
  • exceptionReference: linked DocumentedException when the outcome is approved exception
  • notes: traceability details for reviewers
• Relationships:
  • Many ExceptionRegisterEntry records belong to one GoverningWebsiteSpec.
  • One ExceptionRegisterEntry may reference zero or one DocumentedException.

Entity: MaterialDriftFollowUp

• Purpose: Captures any material page inventory, CTA logic, navigation, or trust messaging change discovered during mapping so it becomes an explicit spec update instead of silent template drift.
• Fields:
  • affectedSpecId: governing website spec whose truth must be updated or followed up
  • driftClass: page inventory, CTA logic, navigation, or trust messaging
  • driftSummary: concise description of what changed materially
  • requiredSpecAction: update existing spec or create follow-up spec
  • targetSpecReference: path to the existing spec or named follow-up spec that owns the change
  • notes: rationale and traceability details
• Relationships:
  • Many MaterialDriftFollowUp records may belong to one GoverningWebsiteSpec.

Entity: LegacyTaskDisposition

• Purpose: Preserves old website implementation task history while marking it as no longer authoritative.
• Fields:
  • originalSpecId: spec that owned the original task
  • originalTaskReference: stable task identifier or short description
  • disposition: superseded by AstroDeck rebuild
  • replacementReference: new plan, spec, or task set that replaces the old task
  • notes: why the original task cannot simply be reopened
• Relationships:
  • Many LegacyTaskDisposition records belong to one LegacyWebsiteImplementation.
  • Many LegacyTaskDisposition records may be associated with one GoverningWebsiteSpec.

Entity: DocumentedException

• Purpose: Captures the narrow approved cases where no adequate AstroDeck primitive exists and custom work is justified, stored as the approved-exception detail inside the exception register.
• Fields:
  • scope: page, section, component, or route slice that needs an exception
  • missingCandidate: statement of which AstroDeck search failed
  • unmetRequirement: the active website-spec requirement that could not be satisfied
  • adequacyFailureReason: why keep or bounded adaptation could not satisfy the requirement
  • boundedDeviation: precise custom work being allowed
  • approvedBy: named website reviewer, owner, or equivalent feature approver
  • approvalReference: spec, review note, or task entry that owns the exception
  • spreadControl: explicit statement of why the exception stays local
• Relationships:
  • One DocumentedException belongs to one PrimitiveMapping.
  • One DocumentedException is represented by one approved ExceptionRegisterEntry.

Validation Rules

• Every continuing or partially valid GoverningWebsiteSpec must have at least one PrimitiveMapping before implementation starts.
• Every CurrentWebsiteSurface must end the planning phase with an explicit disposition.
• Every LegacyTaskDisposition must point to a replacement reference or explicitly state that no replacement work is required.
• Every DocumentedException must name the failed AstroDeck candidate search, the unmet requirement, the adequacy failure reason, the bounded deviation, and the named approver.
• Every material page inventory, CTA logic, navigation, or trust messaging change discovered during mapping must create a MaterialDriftFollowUp record that points to an updated or follow-up website spec.
• Every missing-candidate review must create an ExceptionRegisterEntry with outcome approved exception or no exception required.
• Every replacement task list must name the relevant AstroDeck page, section, component, or mapping activity instead of using generic build wording.
• No PrimitiveMapping may use exception as its disposition without a linked ExceptionRegisterEntry and DocumentedException.

State Transitions

• GoverningWebsiteSpec.classification: unreviewed -> continuing | partially valid | superseded
• CurrentWebsiteSurface.plannedDisposition: discovered -> keep | adapt | remove | redirect
• PrimitiveMapping.disposition: candidate -> keep | adapt | remove | exception
• ExceptionRegisterEntry.reviewOutcome: reviewed -> approved exception | no exception required
• DocumentedException: gap identified -> approved exception record
• LegacyTaskDisposition.disposition: historical -> superseded by AstroDeck rebuild

Notes

• These entities are planning artifacts only. They do not imply new database tables, application models, or runtime services.