Tutorials

Step 1: Requirement Decomposition

The user said: “Calculate tips and split the bill.”

This decomposes into two distinct responsibilities:

Step 2: Project Scaffolding

bashmkdir TipCalculator && cd TipCalculator
boa init
boa block create CalculateTip --layer domain --runtime node
boa block create SplitBill --layer primitive --runtime node

This generates the folder structure, project.boa, blocks.boa, and stub files for each block.

Step 3: CalculateTip Block (Domain Layer)

This block encapsulates the business rule: “a tip is a percentage of the bill.”

block.boaBLOCK CalculateTip 1.0.0
LAYER domain
RUNTIME node
ENTRY index.js
DESC Calculates tip amount and total from a bill.

INTENT User wants to calculate how much tip
  to leave on a restaurant bill.

RULE tipAmount = billAmount * (tipPercent / 100).
RULE totalWithTip = billAmount + tipAmount.
RULE Round both outputs to 2 decimal places.

TAGS tip, restaurant, billing, math

IN billAmount:number!
IN tipPercent:number!
OUT tipAmount:number
OUT totalWithTip:number

FIXTURE {"billAmount":100,"tipPercent":20}
  -> {"tipAmount":20,"totalWithTip":120}

FIXTURE {"billAmount":85.50,"tipPercent":18}
  -> {"tipAmount":15.39,"totalWithTip":100.89}

ERR ValidationError

TypeScriptasync function main() {
  const chunks: Buffer[] = [];
  for await (const chunk of process.stdin)
    chunks.push(chunk as Buffer);
  const envelope = JSON.parse(
    Buffer.concat(chunks)
      .toString("utf-8")
  );
  const { billAmount, tipPercent } =
    envelope.input;

  if (typeof billAmount !== "number" ||
      typeof tipPercent !== "number") {
    console.log(JSON.stringify({
      success: false,
      error: {
        type: "ValidationError",
        message: "Inputs must be numbers"
      }
    }));
    return;
  }

  const tipAmount =
    Math.round(
      billAmount * (tipPercent / 100) * 100
    ) / 100;
  const totalWithTip =
    Math.round(
      (billAmount + tipAmount) * 100
    ) / 100;

  console.log(JSON.stringify({
    success: true,
    output: { tipAmount, totalWithTip }
  }));
}

main();

Step 4: SplitBill Block (Primitive Layer)

This block is pure math with no business context. It lives in the primitive layer because dividing a number by N is a generic operation.

block.boaBLOCK SplitBill 1.0.0
LAYER primitive
RUNTIME node
ENTRY index.js
DESC Divides a total evenly among people.

INTENT Split a total amount equally
  among a group of people.

RULE perPerson = total / people.
RULE Round up to 2 decimal places (ceiling).
RULE people must be at least 1.

TAGS math, split, divide, billing

IN total:number!
IN people:number!
OUT perPerson:number

FIXTURE {"total":100,"people":4}
  -> {"perPerson":25}

FIXTURE {"total":100.89,"people":3}
  -> {"perPerson":33.63}

ERR ValidationError

TypeScriptasync function main() {
  const chunks: Buffer[] = [];
  for await (const chunk of process.stdin)
    chunks.push(chunk as Buffer);
  const envelope = JSON.parse(
    Buffer.concat(chunks)
      .toString("utf-8")
  );
  const { total, people } =
    envelope.input;

  if (typeof total !== "number" ||
      typeof people !== "number" ||
      people < 1) {
    console.log(JSON.stringify({
      success: false,
      error: {
        type: "ValidationError",
        message:
          "total must be a number, people >= 1"
      }
    }));
    return;
  }

  const perPerson =
    Math.round(
      (total / people) * 100
    ) / 100;

  console.log(JSON.stringify({
    success: true,
    output: { perPerson }
  }));
}

main();

Step 5: Register Blocks

Every block must be registered in blocks.boa so the framework can locate them at runtime:

blocks.boaCalculateTip 1.0.0 -> src/DomainBlocks/CalculateTip
SplitBill 1.0.0 -> src/Primitives/SplitBill

The format is: Name Version -> Path. The CLI uses this to resolve CalculateTip@1.0.0 to src/DomainBlocks/CalculateTip/ when executing workflows.

Step 6: Compile and Test

Compile both TypeScript files to JavaScript:

bashnpx tsc --outDir src/DomainBlocks/CalculateTip --target ES2022 --module Node16 --moduleResolution Node16 src/DomainBlocks/CalculateTip/index.ts

npx tsc --outDir src/Primitives/SplitBill --target ES2022 --module Node16 --moduleResolution Node16 src/Primitives/SplitBill/index.ts

Test each block against its fixtures:

bashboa test CalculateTip@1.0.0
boa test SplitBill@1.0.0

Expected output:

  CalculateTip@1.0.0
    Fixture 1: PASS
    Fixture 2: PASS
  2 fixtures passed, 0 failed

  SplitBill@1.0.0
    Fixture 1: PASS
    Fixture 2: PASS
  2 fixtures passed, 0 failed

Step 7: Wire the Workflow

Create workflows/tip-calculator/workflow.boa to chain the two blocks:

workflow.boaWORKFLOW TipCalculator 1.0.0
DESC Calculate tip and split the bill among people.

STEP calc = CalculateTip@1.0.0
  MAP billAmount <- _initial.billAmount
  MAP tipPercent <- _initial.tipPercent

STEP split = SplitBill@1.0.0
  MAP total <- calc.totalWithTip
  MAP people <- _initial.people

How data flows

Step 8: Update project.boa

The project overview file gives any AI (or human) a complete mental model of the project in one read:

project.boaPROJECT TipCalculator 1.0.0
DESC Calculates tips and splits bills among people.

DOMAIN Billing
  CalculateTip: Computes tip amount and total with tip
  SplitBill: Divides a total evenly among people

FLOW TipCalculator: CalculateTip -> SplitBill

Step 9: Run and Validate

Create workflows/tip-calculator/input.json:

input.json{
  "billAmount": 85.50,
  "tipPercent": 18,
  "people": 3
}

Run the workflow:

bashboa run workflows/tip-calculator/workflow.boa --input-file workflows/tip-calculator/input.json

Expected output:

{
  "perPerson": 33.63
}

Validate the entire project:

bashboa validate

  Blocks: 2 registered
  Fixtures: 4 passed, 0 failed
  Workflows: 1 valid
  Status: OK All valid

Understanding the Universal Runtime Protocol (URP)

Every backend block communicates via a simple JSON contract over STDIN/STDOUT:

JSON{
  "block": "CalculateTip",
  "version": "1.0.0",
  "input": {
    "billAmount": 85.50,
    "tipPercent": 18
  }
}

JSON{
  "success": true,
  "output": {
    "tipAmount": 15.39,
    "totalWithTip": 100.89
  }
}

This is why BOA is polyglot — any language that can read STDIN and write STDOUT JSON works. The framework spawns the block as a child process, pipes the envelope in, and reads the result out. Node.js, Python, Go, Rust — it all works the same way.

Why This Architecture Matters for AI

BOA exists to solve the “large codebase + AI context limit” problem. Here’s why each design decision helps: