Skip to content

Singular Blueprint: Standards & Process

Context: This document defines the standard operating procedure for creating and maintaining the "Singular Blueprint" documentation architecture. It ensures consistency across all Domain and Sub-Domain specifications.

1. The Strategy

Our documentation creates a Living Twin of the system, organized by Functional Sub-Domain, not just package name.

Hierarchy

  1. Level 1: Enterprise Landscape (00_ENTERPRISE_LANDSCAPE.md)
  2. Level 2: Domain Strategy (blueprints/0X_DOMAIN_[NAME].md)
  3. Level 3: Sub-Domain Blueprint (blueprints/subdomains/[domain]/[submodule]_blueprint.md)
  4. Level 4: Data Definition (data/dictionary/[domain]/[submodule]_data_definition.md)

2. Templates

A. Level 3: Sub-Domain Blueprint

Goal: Define the Behavior, Mandate, and Process of a specific Sub-Domain.

File Name: [submodule]_blueprint.md Header Template: 

# Sub-Domain Blueprint: [Name]
**Domain**: [Parent Domain] (list all siblings)
**Logical Sub-Domain**: [Name] (Composite)
**Physical Packages**: `[package-a]`, `[package-b]`
**Related Documents**: [Data Definition](./../../../../07_data/dictionary/[domain]/[submodule]_data_definition.md)
**Context**: This document defines the **Process Models** and **Mandate** for the [Name] stack.
**Status**: [Stable | Beta | Planned]

Required Sections: 1. Mandate: Single sentence describing the responsibility. 2. Capabilities: Table of Features (Capability | Description | Component). 3. Process Models: Mermaid Sequence Diagrams for key "Happy Path" workflows. 4. State Machines: Mermaid State Diagrams for complex entities (e.g. Lifecycle). 5. Interface Definitions: Key Service methods.

B. Level 4: Data Definition Object (DDO)

Goal: Define the Structure, Relationships, and Truth of the data.

File Name: [submodule]_data_definition.md Header Template: 

# Data Definition Document: [Name]
**Domain**: [Parent Domain] (list all siblings)
**Logical Sub-Domain**: [Name] (Composite)
**Physical Packages**: `[package-a]`, `[package-b]`
**Related Documents**: [Process Blueprint](./../../../../01_architecture/blueprints/subdomains/[domain]/[submodule]_blueprint.md)
**Context**: This document defines the **Data Structures**, **Relationships**, and **Field-Level Truth**.
**Source**: `[path/to/schema.ts]`

Required Sections: 0. Entity Relationship Diagram (ERD): Mermaid erDiagram showing Core Entities and Foreign Keys. 1. [Entity Name]: Table of fields. * Columns: Field | Type | Required | Description.

3. Maintenance Process

When to Update?

  • Logic Change: If you change service.ts (e.g., adding a step to a workflow), you MUST update the Process Model in the Blueprint.
  • Schema Change: If you change schema.ts (e.g., adding a field), you MUST update the Data Definition.

How to Create a New Blueprint?

  1. Identify Boundaries: Does this correspond to a Formal Sub-Domain (e.g., "Governance") or just a utility?
  2. Scaffold Files: Create the empty _blueprint.md and _data_definition.md files.
  3. Draft Process: Graph the primary user stories using Mermaid.
  4. Draft Data: Document the Zod schema and draw the ERD.
  5. Cross-Link: Ensure the headers link to each other.
  6. Verify: Open in Typora to check rendering.

4. Changelog Standard

Every Blueprint and Data Definition MUST end with a Changelog table to ensure traceability.

Format: 

## Changelog
| Date | Author | Description | Reference |
| :--- | :--- | :--- | :--- |
| 2026-01-24 | Antigravity | Initial creation after Migration | [Walkthrough](../../../../artifacts/walkthrough.md) |