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.

1.1 The Trifold Philosophy

Every Blueprint MUST serve a dynamic, bi-directional role in the system lifecycle. It is not a static artifact; it is a "Tri-Fold" tool:

  1. Forward (Intent): It prescribes how the system should be built. It defines the "Reasoning Layer" and architectural decisions before code is written.
  2. Backward (State): It reflects how the system is built. It acts as the map for the "Enforcer" implementation and must strictly match the code (verified by MRI).
  3. Evolutionary (Basis): It provides the stable foundation to define and evaluate future changes. It is the baseline against which "Gap Analysis" is performed to enable safe evolution.

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) |