Lesson 4 - Improve Intake and Review Pages

This lesson is where the HarborFlow tool starts to feel real.

Maya already has the right core record, but the first version still feels like a generic request tracker. The next step is to make the pages fit how HarborFlow’s team actually submits, reviews, and works requests.

Keep editing the same blueprint.toml. In this lesson, you are refining the pages that already point at ExceptionRequest.

The Goal

By the end of this lesson, the app should feel usable for:

• account managers who submit exception requests
• ops managers who review them
• directors who need enough context to approve unusual cases

Improve The Intake Form

The first form should ask for what the team really needs to make a decision.

For HarborFlow, that usually means:

• a clearer title
• the customer name
• the exception type
• the priority
• a justification that explains why the exception is needed

Practical improvements:

• use labels that match the team’s language
• make required fields truly required
• remove any field that does not affect triage or approval
• add success messaging that tells submitters what happens next

For HarborFlow, the intake form might evolve into something like:

[page."/requests/new"]
title = "Submit Exception Request"
layout = "form"
auth = "required"

[page."/requests/new".form]
entity = "ExceptionRequest"
method = "create"

[[page."/requests/new".form.fields]]
name = "title"
type = "text"
label = "Request Title"
required = true

[[page."/requests/new".form.fields]]
name = "customerName"
type = "text"
label = "Customer Name"
required = true

[[page."/requests/new".form.fields]]
name = "exceptionType"
type = "text"
label = "Exception Type"
required = true

[[page."/requests/new".form.fields]]
name = "priority"
type = "select"
label = "Priority"
required = true
options = [
  { value = "low", label = "Low" },
  { value = "medium", label = "Medium" },
  { value = "high", label = "High" }
]

[[page."/requests/new".form.fields]]
name = "justification"
type = "textarea"
label = "Business Justification"
required = true
rows = 6

[page."/requests/new".form.onSuccess]
redirect = "/requests/{id}"
message = "Request submitted. Operations will review it next."

Make The List Page Useful

The list page is the ops team’s working queue. It should help them answer:

• what is new?
• what is urgent?
• what is still waiting on review?

For HarborFlow, that means tuning the list toward operational triage instead of generic display.

Typical improvements:

• sort by newest or highest priority
• make the status and priority fields visible
• make titles and page labels more specific
• reduce visual noise so the queue is easy to scan

That list page might look like:

[page."/"]
title = "Customer Exception Requests"
layout = "list"
auth = "required"

[page."/".query.requests]
entity = "ExceptionRequest"
orderBy = { createdAt = "desc" }

Make The Detail Page Reviewer-Friendly

The detail page should tell the reviewer whether they can make a decision immediately.

For HarborFlow, the detail page should make it easy to understand:

• what the request is
• who submitted it
• why it matters
• how urgent it is
• what decision needs to happen next

If a reviewer has to hunt for context, the page is not doing enough.

A simple detail page baseline is:

[page."/requests/:id"]
title = "Exception Request"
layout = "detail"
auth = "required"

[page."/requests/:id".query.request]
entity = "ExceptionRequest"
where = { id = "$params.id" }

HarborFlow Example Changes

By the end of this lesson, Maya might make changes like:

• rename the home page from Requests to Customer Exception Requests
• add customerName and exceptionType to the form
• change details to Business Justification
• show priority and status prominently in the list and detail pages
• tighten the success message so submitters know the request is now in review

Lesson Output

By the end of this lesson, you should have:

• a better intake form
• a more useful queue page
• a detail page that supports actual review work

Use the Blueprint Reference if you need to look up form fields, queries, or detail-page options while refining these pages.

What Changes In blueprint.toml

In this lesson, you are mainly editing the page sections:

• update the list page title, auth, and query
• update the form page fields, labels, and success behavior
• update the detail page so reviewers can inspect one request clearly

The entity stays mostly stable here. The emphasis is on page configuration and form design.

Zebric Concepts In This Lesson

• Pages: list, form, and detail layouts become more specific to the workflow
• Forms: field labels, required rules, and success behavior start mattering
• Queries: list ordering and detail lookups define what each page shows

Next Lesson

Continue to Lesson 5 - Add Permissions and Guardrails.