Skip to main content
Architecture10 min read

901 - What an application is

An application is a whole system built on Plexara and held as one record: a database schema, the automations that do the work, the forms and endpoints people and systems use, the events that drive it, and the pages people see. The agent builds the parts, an administrator releases them as one pinned set, and the record answers what the system is made of, what runs, and who decided.

What you will take away from this lesson

The 600 series taught the agent to write an automation. The 700 series put automations at addresses other systems call and people fill in. Each of those is a part. A business does not run on parts; it runs on systems: an order system, an intake desk, a supplier program, a shop. On Plexara a system is an application, and an application is something your agent builds whole.

This series builds one on the demo tenant: a shop for ACME Corp with a product catalog, a checkout that takes stock as it records the order, an order confirmation, nightly upkeep and a storefront. This first lesson covers what the application record is, what it holds, and why holding it as one thing changes what an agent can safely be trusted to build.

Learning Objectives

  1. 01Say what an application is: one record naming every part of a system built on Plexara, released as one pinned set.
  2. 02Name the six kinds of part and what each contributes to a working system.
  3. 03State the four questions the record answers that a folder of scripts cannot.
  4. 04Say who reads an application, who edits it, and who alone releases it.
  5. 05Follow the order an agent builds an application in, and know that a system can grow into one.

Where this lesson sits

The 900 series assembles the parts the earlier series taught into whole systems. It assumes the automations of the 600 series and the endpoints and forms of the 700 series, and adds what a system needs beyond them: a database of its own, a release, and a way back.

900 Series: Applications

Open index

The 900 series assembles what the 600 series and the 700 series taught one part at a time: automations, endpoints and forms become one application with a database of its own, released as a whole.

The unit an agent builds

An application is a system built entirely on Plexara: its data in an application database, its API and pages as endpoints and forms, its side effects as events, its interface as portal assets, and its upkeep as scheduled automations. One record names all of it.

This is the unit that matters. A capable model writes a correct automation in one turn. What an organization needs is the thing those automations add up to, held in a form a person can read, release and reverse. The application is that form.

What an application is made of

Schema

one per application

A schema on an application database: the tables, constraints and policies the application commits its rows to, created and changed only by migrations. The application owns it, and only the application’s own automations log in to it. Lesson 902.

Automations

any number

The managed scripts that do the work, each saved with tests and versioned. An automation runs on demand, on a schedule, once per event, or once per request, and inside an application it runs at the version the release pins. Lesson 903.

Endpoints and forms

bindings of automations

An endpoint or a form is an automation’s binding to an address, so it travels with its automation. The JSON API a storefront calls and the checkout a customer fills in are both parts by way of the automations behind them.

Webhook sources

any number

Where events come from: another system’s webhook, a form’s submissions, or the application’s own database writing a row for each new order. An automation that names a source runs once for each event it stores.

Assets

any number

The portal assets that are the application’s face: a storefront page, a dashboard, a report. The portal serves an asset part at the version the release pins.

Site environment

optional

One environment of a site, so a website and the application behind it move together: a release points the environment at the release the environment before it serves, and a rollback restores it. Lesson 906.

A part belongs to one application. Adding a part another application holds is refused, and the refusal names the holder, so two systems never quietly share a moving piece.

What the record answers

A folder of scripts and a diagram on a whiteboard describe a system until the first change. An application record cannot drift from the system, because it is the system’s own inventory and the only way its parts go live.

Four questions the record answers

  1. 1

    What is this system made of?

    The record lists every part by name and kind. Nobody reconstructs a system from naming conventions or from memory; the application’s page is the inventory.

  2. 2

    What is running right now?

    Each automation and asset is pinned at a version by the current release. A newer saved version is shown beside the pin as waiting, and it runs nowhere until a release.

  3. 3

    Who decided that?

    Every release names the administrator who made it, when, what it changed and the note they wrote. The history of the system is the list of its releases.

  4. 4

    What would change next?

    Before a release is made, the record states what it would pin, which migrations it would apply, and anything it would refuse. The decision is made on a statement of fact.

These four answers are the difference between software an agent wrote and software an organization runs. An agent produces working parts in minutes. The application record is what makes the result legible, attributable and reversible, which is what lets it run unattended.

Asking for one

Nobody builds an application by clicking through its parts. The owner describes the system, and the agent builds it.

The request, as a person types it

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.

The request names an outcome and one decision the person keeps: nothing is released until they have read what the release contains. Everything between is the agent’s work, and the agent begins by reading the platform’s own knowledge page on building applications, which states the order of work below.

The record and its schema

The agent’s first two calls create the record and add the schema. Both are small, and both matter: from here on every other part has something to belong to.

Creating the application and giving it a schema

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": "create",
    "name": "shop",
    "description": "The ACME shop: catalog, checkout, order
                    confirmation and storefront."
  }

← {
    "id": "app-shop",
    "name": "shop",
    "owner_email": "[email protected]",
    "current_release": 0,
    "parts": []
  }

→ manage_application
  {
    "command": "add_part",
    "application": "shop",
    "kind": "schema",
    "part_id": "acme-shop/shop"
  }

← {
    "name": "shop",
    "connection": "acme-shop",
    "schema": "shop",
    "current_release": 0,
    "parts": [ { "kind": "schema", "id": "acme-shop/shop" } ]
  }

The name is a lowercase slug, unique on the deployment, and the person who asked is the owner. current_release is 0: the application exists, and nothing has been released.

The schema is added as a part, named by its connection and schema. From this call on, the schema exists inside the application and nowhere else: migrations are added to it through the application, and the platform has created the role the application’s automations will log in as. Lesson 902 covers both.

Who reads, who builds, who releases

An application separates building from releasing. The separation is what lets the building go fast.

Who does what

Everyone signed in

reads

Any signed-in person can open an application and see its parts by name, the version each is pinned at, and its releases. An asset the reader cannot open is listed without its name.

The owner

builds

One owner, the person the agent built it for. The owner edits the description and adds the parts they own: their automations and their assets.

An administrator

releases

Only an administrator releases and rolls back. A release changes the code behind an address the outside world calls and runs migrations on a database, which is the same authority binding an endpoint and applying a migration already require. An administrator also adds webhook sources, and alone removes a part the current release pins.

The split is deliberate. The owner and their agent build as fast as they can think. The step that changes what the business runs on belongs to an administrator on your team, it is one action, and it is recorded.

The order of work

An application is built in six steps, and the rest of this series follows them.

The order an agent builds in

  1. 1

    The application, then its schema

    Create the record and add the schema as a part. Every table, constraint and policy is then a migration. The schema is the contract the automations are written against.

  2. 2

    Automations against the schema

    Each automation is written with tests that run on a throwaway copy of the database built from the migrations, so constraints and policies are exercised for real.

  3. 3

    The front

    An endpoint for the JSON API, a form for anything a person submits, an asset or a page for what people see.

  4. 4

    Side effects as events

    A row the application writes becomes an event an automation handles. The confirmation is sent after the order commits, by a run of its own, never by a call made inside the transaction.

  5. 5

    Upkeep as a schedule

    Maintenance and reports run on a timer, as parts of the same application.

  6. 6

    A release

    An administrator releases, which applies the migrations and pins every part. The system is live at that moment and not before.

The agent does not improvise this order. It reads it from a knowledge page the platform documents itself with, so every agent that builds an application on your deployment builds it the same way.

Starting small

The six steps describe a system built from nothing. A system that already exists joins the same way, one part at a time.

Applications in the portal

The portal’s Applications section lists every application with its owner, its number of parts and its current release.

The Applications section of the portal: a note that an application names what a system is made of and is released as one unit, Import and New application buttons, and a table of two applications, shop with five parts at release 3 and intake with one part and no release, each with its owner and when it was last updated.
The Applications section. Each row is a whole system: its owner, how many parts it has, and the release in force. An application that has never been released shows None.

Key terms

Four terms carry the rest of the series.

Key Terms

Application
One record naming every part of a system built on Plexara: a schema, automations, webhook sources, assets and optionally a site environment. Built by an agent, released by an administrator as one pinned set.
Part
A member of an application. A part belongs to at most one application, and inside a released application it runs or is served at the version the release pins.
Owner
The one person an application belongs to. The owner edits it and adds the parts they own; an administrator can move it to another owner.
Release
The act that applies an application’s pending migrations and pins each automation and asset at its newest version. An administrator’s action, recorded with what it changed.