Skip to main content
Product12 min read

907 - Capstone: the shop, end to end

One request, one application. The shop assembled in the order an agent builds it: the record and its schema, five migrations, a checkout, an API, a confirmation event, nightly upkeep, a storefront, and the first release. Then a change, a second release, and a rollback, with what the administrator reads at each step.

What you will take away from this lesson

Six lessons took the shop apart. This one puts it together and runs it through the life every real system has: it is built, it is released, it is changed, the change is wrong, and it is put back. Three sentences from a person drive the whole of it.

Read this lesson as the answer to a practical question. What does it take, on Plexara, to go from wanting a system to running one you can trust? It takes a request, an agent, and an administrator who reads one page and presses one button.

Learning Objectives

  1. 01Follow one application from a single request to its third release.
  2. 02Name every part of the shop, what runs it and what it is responsible for.
  3. 03Read the shop’s five migrations as a statement of its rules.
  4. 04Say what the owner typed, what the agent did and what the administrator decided at each step.
  5. 05Read an application’s release history as the record of how a system changed.

Three requests

The shop’s whole history, from nothing to its third release, was driven by three things a person typed.

Everything a person typed

1. Build a small shop for ACME on Plexara as an application
   called shop. It needs a product catalog with stock, a checkout
   that records an order and takes the stock in one step, an order
   confirmation, and a storefront page. Use the acme-shop
   application database. Show me what the first release would
   contain before anything is released.

2. Add gift wrapping to the shop: a checkbox per line on the
   checkout, a wrap fee added to the total, and a note on the
   storefront. Do not release it. Tell me what the release would
   change.

3. Gift-wrap totals are wrong on orders with more than one line.
   The shop has been rolled back. Find the cause, fix it, prove
   the fix with a test on the database, and tell me what the next
   release would change.

Each request ends by asking for the same thing: a statement of what a release would change. The owner never asks the agent to release. Releasing is not the agent’s to do, and the owner’s habit of asking for the statement is what gives the administrator something exact to decide on.

What was built

The first request produced an application of seven parts.

The shop, part by part

acme-shop/shop

schema

Products, inventory, orders, order lines and the outbox. Holds the rules: stock never negative, a customer sees only their own orders, the shop’s automations write and never delete an order.

shop-checkout

automation, once per request

A form. Places the order, its lines and the stock decrements in one transaction, as the signed-in customer, at the shop’s prices.

shop-api

automation, once per request

The JSON API: active products with their stock, and the caller’s own orders.

shop-confirmation

automation, once per event

Runs once for each new order and posts its confirmation to the order-confirmations channel.

shop-maintenance

automation, on a schedule

Nightly: analyzes the database and vacuums the tables that churn.

shop-orders-outbox

webhook source

Reads the outbox table and stores one event per order row.

storefront

asset

The page that presents the shop and links to the checkout. Its product list comes from the API.

Any of the four automations can also be run on demand by its owner or an administrator. Seven parts, each with one job, each replaceable without touching the others.

The rules, as migrations

The schema’s five migrations are short enough to read as a list of what the shop will never allow.

Five migrations

1 catalog

Products and inventory. A price is never negative. Stock is never negative.

2 orders

Orders and order lines. A line belongs to an order, names a real product and has a positive quantity.

3 own_orders

Row-level security on orders and lines, forced, keyed on the caller’s email.

4 outbox

From the platform’s template: an outbox table and a trigger that records each change to an order.

5 roles

shop_read and shop_write, created only when absent, with grants table by table. The platform grants shop_write to the shop’s run role.

Each was reviewed, planned and applied from zero on a throwaway database before it was saved. All five are applied to the real database by release 1 and by nothing before it.

How it was built

The agent followed the order of work from lesson 901.

From request to release 1

  1. 1

    Read how applications are built

    The agent fetches the platform’s knowledge page on applications and follows its order of work.

  2. 2

    Create the record and add the schema

    manage_application create, then add_part with kind schema. The run role now exists.

  3. 3

    Add and plan five migrations

    manage_schema add for each, reading the review’s findings and the plan, then describe to read the schema back.

  4. 4

    Write and test four automations

    manage_script for each, with tests that open a copy of the database. A save is refused until its tests pass.

  5. 5

    Preview the checkout, save the storefront

    The form is previewed as a customer will see it. The storefront is saved as an asset.

  6. 6

    Add the parts and report

    add_part for each automation and the asset, then get. The agent reports the pending pins and migrations and that nothing would be refused.

  7. 7

    Hand over

    An administrator binds the endpoints, adds the outbox source and its part, reads the application’s page, and releases.

Six of the seven steps are the agent’s. The seventh is a person’s, and it is the only one that changes what the business runs on.

What each person did

Across the first release, the gift-wrap change and the rollback, three parties did three different kinds of work.

Who did what, across the whole build

The owner

three requests

Read three plain-language reports of what a release would change, previewed a checkout form, and looked at a storefront. Never read a line of code and never needed to.

The administrator

two releases, one rollback

Read the application’s page: the parts, the pinned and waiting versions, the pending migrations, an empty list of problems. Compared the diagram with the current release before release 2. Rolled back with a one-line note when the totals were reported wrong.

The agent

everything else

Wrote the schema, the automations, the tests and the storefront, corrected what the review and the tests refused, and stated at each step what was pending. Released nothing.

This is the division of labor the platform is built for. Judgment about the business stays with people, in two places: what to ask for, and when it goes live. The work between those two points is the agent’s.

The history

After the third request the shop has three releases, and the record of them is the record of the system.

The shop’s history, as the platform keeps it

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_application
  { "command": "releases", "application": "shop" }

← { "releases": [
    {
      "number": 3, "action": "rollback", "restored": 1,
      "migration_version": 5,
      "note": "Gift-wrap totals were wrong on multi-line orders.",
      "changes": {
        "parts": [
          { "kind": "script", "part_id": "shop-checkout", "from": 4, "to": 3 },
          { "kind": "asset",  "part_id": "storefront",    "from": 5, "to": 4 }
        ],
        "applied": [], "reverted": [6] }
    },
    {
      "number": 2, "action": "release",
      "migration_version": 6,
      "note": "Gift wrapping.",
      "changes": {
        "parts": [
          { "kind": "script", "part_id": "shop-checkout", "from": 3, "to": 4 },
          { "kind": "asset",  "part_id": "storefront",    "from": 4, "to": 5 }
        ],
        "applied": [6], "reverted": [] }
    },
    {
      "number": 1, "action": "release",
      "migration_version": 5,
      "note": "First release: catalog, checkout, API,
               confirmation, upkeep, storefront.",
      "changes": { "parts": [ 5 parts pinned ],
                   "applied": [1, 2, 3, 4, 5], "reverted": [] }
    }
  ] }

Three entries tell the whole story: what went live first, what changed, and that the change was withdrawn and why. Migration 6 added a nullable column and had a down, so the rollback reverted it. The fixed checkout, version 5, is saved and waiting. Release 4 will pin it and apply the migration again, when an administrator decides to.

An application's page in the portal with its parts grouped by kind, automations, assets, webhook sources and schema, each with the version release 3 pins, and an Add parts button.
The page an administrator reads before a release: every part by name, the version in force, and what is waiting.

The shop in numbers

The shop in four numbers

parts, each with one job
7
migrations, built from zero before saving
5
requests typed by the owner
3
step to put the previous release back
1

The shop is small on purpose. Nothing about the method depends on its size. An intake desk, a returns system, a supplier program or a reservations system is the same six steps with different tables.

Custom software, without the cost of custom software

Key terms

Four terms summarize the series.

Key Terms

Application
One record naming every part of a system built on Plexara, built by an agent and released by an administrator as one pinned set.
Release history
Every release and rollback of an application, newest first, each with its pins, what it changed, who made it and their note.
Pending
What the next release would change. The statement an owner asks the agent for and an administrator decides on.
System of record
The store whose rows are the truth about what a system decided. An application database is one, because its rules are enforced by the database on every write.