Blueprint Language Tutorial

Blueprint is a domain-neutral language for declaring a system. A domain blueprint is the program. The shared database, API, UI, policy, workflow, and execution layers are interpreters of that program.

This course starts with one field and ends with a regulated, authenticated, cross-module system whose database shape, governed revisions, policy, evidence, events, effects, and readiness can be inspected from the same declaration.

What you will build

The running example is an Operations module with controlled areas and equipment. By the end, it includes:

• typed fields, labels, references, and derived form values;
• facets, entities, relationships, and projections;
• lifecycle actions with declarative rules;
• tenant-safe database posture and query hints;
• generated tables, filters, editors, detail tabs, and action placements;
• module exports and cross-module contributions;
• actors, assignments, tasks, evidence, audit, events, and effects;
• immutable execution records that can drive timelines and replay;
• governed business revisions and exact database inspection;
• provider-neutral authentication, IAM catalogs, session policy, and electronic signatures;
• system readiness, extension-binding diagnostics, and production checks.

Core declaration examples use:

import 'package:vyuh_blueprint/vyuh_blueprint.dart';

Runtime chapters name their additional owning packages explicitly: vyuh_blueprint_protocol, vyuh_blueprint_server, vyuh_blueprint_ui, vyuh_studio_ui, and vyuh_iam.

Learning path

Stage	Chapter	Tangible result
1	Think in Blueprint	Separate declaration, configuration, and execution.
2	Fields, types, and rows	Declare typed, reusable field tokens.
3	Facets and entities	Assemble one entity from coherent facets.
4	Relationships and projections	Connect entities without leaking raw IDs into the UI.
5	Actions, rules, and lifecycles	Declare governed behavior without domain-specific runtime code.
6	Modules and assembly	Compose bounded contexts and cross-module contributions.
7	Database, security, and seed hints	Lower declarations into a secure physical plan.
8	UI, queries, and forms	Generate adaptable UI while retaining extension points.
9	Actors, work, and policy	Resolve who may act and how work is assigned.
10	Runtime execution	Turn an action request into an ordered transaction.
11	Evidence, audit, and replay	Preserve who, when, what, where, and why.
12	Extension points	Add behavior without weakening the typed core.
13	Operations capstone	Put the complete language together.
14	Governed revisions and database inspection	Evolve controlled records while inspecting the exact generated schema.
15	Authentication, IAM, and electronic signatures	Connect identity, product authorization, sessions, and signed actions.
16	System readiness and production patterns	Prove declaration, database, delivery, and client bindings as one system.

Use the coverage matrix to find where every vocabulary family is introduced and where its exhaustive API reference lives.

How to use this course

1. Read chapters in order the first time.
2. Type the examples instead of copying them.
3. Run BlueprintValidator.validate after each structural change.
4. Compare the declaration with the generated DB, protocol, and UI surfaces.
5. For production design, follow the links into the Vocabulary Reference and Replay Contract.

One invariant to remember

The runtime may switch on Blueprint vocabulary types. It must not switch on industry names, module names, entity names, or action names.

Quick retrieval check

Before continuing, answer without looking back:

1. Which object is the program: the grammar, the domain blueprint, or the runtime?
2. Which layer is allowed to know that an area is a pharmaceutical concept?
3. What must remain generic when another industry supplies a different blueprint?

The answer is developed in Chapter 1.