Creating Blueprints

Blueprints are JSON-defined bundles of objects, relationships, and (optionally) a starter diagram. They live inside content packs — versioned bundles that ship with DesignFoundry or that admins can author for their organization.

This page describes the admin workflow for packaging architecture into a new blueprint.

Important: Authoring blueprints requires the Admin role and access to the content-pack source files (in your tenant’s content-pack repository). End users only browse and apply blueprints.

When to author a new blueprint

• Your organization has a recurring pattern (e.g. a standard SaaS onboarding architecture) that teams build from scratch each time.
• A regulatory framework (DORA, NIS2, HIPAA) has a canonical reference structure your auditors expect to see.
• You’re capturing the as-built shape of a key system as a starter for new projects.

Two paths

A. Promote from existing project content

The fastest path: model the pattern as objects + relationships in a sandbox project, then export.

1. Build the pattern in a project — give every object a stable, descriptive name (this becomes the import idempotency key).
2. Open Settings → Content Packs → Author.
3. Select the source project and the objects/relationships to include.
4. Click Export as blueprint. DesignFoundry generates the blueprint JSON and downloads a .blueprint.json file.
5. Place the file under your content pack’s blueprints/ directory and submit it to the pack’s source repo.

B. Author by hand

For more precise control (or for blueprints with no in-app representation yet), write the JSON directly.

Blueprint schema

{
  "id": "saas-onboarding-v1",
  "version": "1.0.0",
  "name": "SaaS Onboarding Reference",
  "description": "Standard customer-onboarding flow for B2B SaaS — auth, provisioning, billing.",
  "category": "Generic",
  "referenceFramework": "TOGAF 9.2",
  "diagramType": "archimate",
  "tags": ["saas", "onboarding", "iam"],
  "objects": [
    {
      "id": "obj-auth-service",
      "type": "application",
      "name": "Authentication Service",
      "description": "OIDC-compliant identity provider.",
      "status": "live",
      "fields": { "criticality": "high" },
      "position": { "x": 100, "y": 100 }
    }
  ],
  "relationships": [
    {
      "sourceId": "obj-auth-service",
      "targetId": "obj-user-portal",
      "type": "serves",
      "label": "auth"
    }
  ],
  "diagram": {
    "nodes": [],
    "edges": []
  }
}

Required top-level fields

Object entries

Each object needs id (local to the blueprint), type (must match a registered object type), and name. Optional: description, status, fields (extra type-specific properties), position (for diagram placement), parentId (for hierarchy), extensions (typed extension payloads keyed by extension type).

Relationship entries

sourceId and targetId reference local object IDs (not the global UUIDs). type must be a valid relationship type (serves, realizes, composes, etc.). Optional label overrides the default edge label.

Validation

Every blueprint goes through Zod schema validation at load time. Common rejections:

• Object type not in the registered type catalog.
• Relationship sourceId or targetId missing from the objects array.
• BPMN blueprints with malformed start/end events or disconnected flows (the BPMN validator runs after import).

Run npm run blueprints:validate from the content pack repo before submitting.

Idempotent import

Blueprint imports are name-keyed: re-importing an updated version of a blueprint matches existing objects by (name, type) and updates them in place — it doesn’t duplicate. Users can re-apply at will. If they renamed an imported object, the next reapply imports a fresh copy (the rename broke the idempotency key).

Versioning

Bump the version on every published change. The gallery shows the version on each card. When users re-apply a newer version of a blueprint they already imported, DesignFoundry shows a diff of changed objects/relationships and asks for confirmation.

Submitting

1. Open a PR against your content-pack repository with the new .blueprint.json under blueprints/.
2. CI runs schema validation and (for BPMN blueprints) flow integrity checks.
3. On merge, the content pack auto-publishes; tenants on that pack see the new blueprint after the next cache refresh (typically within minutes).

See also

• Overview — what blueprints are.
• Browsing Blueprints — the user-facing gallery.
• Applying Blueprints — importing into a project.