Lesson 2 - Generate the First Blueprint With AI

In this lesson, you use the workflow brief from Lesson 1 to generate a first-pass Zebric blueprint.

We’ll use this blueprint as a first draft, and continue to refine it as we progress through the lessons.

In the HarborFlow story, Taylor takes her plain-language process for customer exception requests and asks an LLM to turn it into a starting blueprint.

Starting with this lesson, and through Lesson 5, you will do all of this work in the Zebric Playground — a browser sandbox that runs blueprints without installing anything. Lesson 6 is where you install the CLI, once you want to see Zebric running on your own computer.

Recommended Prompt

Use a prompt like this:

Create a Zebric blueprint.toml for this internal tool - based on the docs at https://docs.zebric.dev:

[paste your workflow brief here]

Requirements:
- include one main entity for the request being tracked
- include a list page at "/requests"
- include a form page for creating a new record
- include a detail page for reviewing a record
- use realistic status values
- keep the first version simple
- output valid TOML only

For HarborFlow, the prompt brief would describe:

• account managers submitting customer exception requests
• ops managers reviewing them
• statuses like submitted, reviewing, approved, rejected, and completed
• a list page, intake form, and review page

What Good LLM Output Looks Like

A good first draft should give you:

• one clear primary entity
• sensible field names
• a short list of statuses
• a list page
• a form page
• a detail page

It does not need to include:

• perfect permissions
• advanced workflows
• notifications
• every edge case in the business process

For Taylor, a good first draft gives something concrete to run and improve.

Run It In The Playground

Open playground.zebric.dev/examples/request-approval.

That example is the closest existing match to HarborFlow’s process: a purchasing-approval flow with three roles (requester, manager, admin), a manual approval workflow, an audit trail, and simulated Slack notifications. You will reshape it into the exception-request tool over the next few lessons instead of starting from a blank file.

Paste your LLM-generated draft into the Editor tab, replacing the bundled TOML, and check two things:

• the Validation tab, which replaces zebric validate — it parses your draft, checks that every page query and form points at a real entity, and flags anything unrunnable
• the Preview tab inside the simulator panel, which replaces zebric dev — it renders your actual pages against in-memory data, live, as you type

Then review the generated app like a power user:

• does the record type match the business process?
• are the statuses usable?
• does the form ask for the right information?
• does the detail page show what a reviewer actually needs?

In HarborFlow’s case, Taylor is checking whether the app feels like it will actually be useful for all of the users.

A quick note on roles: the Playground’s account switcher offers requester, manager, and admin — these stand in for HarborFlow’s account managers, ops managers, and directors for the rest of this course. Keep your blueprint’s role checks using those three values so you can actually test them by switching accounts in the toolbar.

If The LLM Gets It Wrong

If the output is invalid or overcomplicated:

1. simplify the prompt
2. ask for fewer entities and fewer pages
3. ask for TOML only
4. fall back to the bundled example below

Use the bundled example if you want to. The goal of the course is to go through the process of going from business process to running application.

The Bundled Starting Point

Click Reset in the Playground to return to the example’s original blueprint. Its data model is:

[[entities]]
name = "TeamMember"
fields = [
  { name = "id", type = "ULID", primary_key = true },
  { name = "name", type = "Text", required = true },
  { name = "email", type = "Email", required = true },
  { name = "role", type = "Enum", values = ["requester", "manager", "admin"], required = true },
  { name = "department", type = "Text" }
]

[[entities]]
name = "ApprovalRequest"
fields = [
  { name = "id", type = "ULID", primary_key = true },
  { name = "title", type = "Text", required = true },
  { name = "amount", type = "Integer", required = true },
  { name = "status", type = "Enum", values = ["draft", "submitted", "pending_manager", "approved", "rejected"], default = "draft" },
  { name = "category", type = "Enum", values = ["software", "hardware", "services", "training"], default = "software" },
  { name = "requesterId", type = "Ref", ref = "TeamMember.id" },
  { name = "managerId", type = "Ref", ref = "TeamMember.id" },
  { name = "justification", type = "LongText" },
  { name = "createdAt", type = "DateTime", default = "now" }
]

Notice the double square brackets: [[entities]] instead of [entity.Name]. Both are valid ways to write a blueprint, but do not mix the two styles in the same file. Because the bundled Playground example already uses [[entities]], [[pages]], and [[workflows]], the rest of this course keeps using that style for snippets you paste into the Playground. The Blueprint Reference documents the alternate [entity.Name] and [page."/path"] style if you start from a blank file later.

The example also ships a dashboard page, a request list and form, a detail page with an action bar, a working ApproveRequest workflow, an ApprovalAudit entity for tracking who did what, and simulated Slack/console notifications. You will reshape the parts that matter to HarborFlow over the next few lessons. You can keep the audit trail, but when you rename the main request entity in Lesson 3, you will update the audit reference to point at the new name.

Lesson Output

By the end of this lesson, you should have:

• a runnable blueprint open in the Playground, either your LLM’s draft or the bundled example
• a short list of what needs to change next
• a decision on whether to keep the LLM draft or reshape the bundled example

From this point on, keep editing the same blueprint in the Playground’s Editor tab as you move through Lessons 3 through 5.

What Changes In blueprint.toml

By the end of this lesson, your blueprint should contain:

• project metadata
• one or more entities, including a main record to track
• a list page
• a create form page
• a detail page

Checkpoint Blueprint

Use lesson-2-blueprint.toml if you want a complete, working file for this point in the course. It follows the bundled Request Approval example before you reshape it into HarborFlow’s exception process, with console notifications and built-in query workflow steps so it can also run locally without Slack credentials or sample-only plugins.

Once you install the CLI in Lesson 6, you can validate any checkpoint file with:

zebric validate --blueprint lesson-2-blueprint.toml

Zebric Concepts In This Lesson

• Blueprints: you now have the first working TOML application definition
• Entities: the first draft of the record type appears here
• Pages: list, form, and detail layouts become concrete routes
• Playground: the Editor, Validation, and Preview tabs replace zebric validate and zebric dev while you are still shaping the app

Next Lesson

Continue to Lesson 3 - Shape the Data Model.