Skip to main content

L3: Full Platform

L3 is the complete adoption level. You call defineApp, compileApp, and createAppRuntime in sequence, and the platform owns the full execution model.

Why this exists​

At L2, you integrate the runtime into an existing server. At L3, the platform is the server. You write a spec, the compiler produces artifacts, and the runtime handles routing, dispatch, surface binding, and execution. There is no framework to integrate with and no server to maintain separately.

L3 is appropriate when you are building new. If you have an existing server and want to add Gooi incrementally, start at L2.

Installation​

bun add @gooi/app @gooi/app-runtime
# or
npm install @gooi/app @gooi/app-runtime

Usage​

import { readFileSync } from "node:fs";
import { defineApp } from "@gooi/app/define";
import { compileApp } from "@gooi/app/compile";
import { createAppRuntime } from "@gooi/app-runtime/create";

// Step 1: validate and parse the spec
const spec = defineApp({ yaml: readFileSync("./app.yml", "utf-8") });

// Step 2: compile to a deterministic artifact
const bundle = compileApp({ spec });

// Step 3: activate the runtime with bound providers
const runtime = createAppRuntime({ bundle, hostPorts });

// Step 4: invoke any entrypoint
const result = await runtime.invoke({
  entrypointKind: "mutation",
  entrypointId: "submit_message",
  input: { message: "hello from L3" },
  authContext,
});

What you get at L3​

At L3, you have:

  • End-to-end declarative execution. Your spec is the application. The compiler produces the artifact. The runtime executes the artifact. You do not write route handlers, middleware, or validation logic.
  • All surfaces wired. HTTP, web, CLI, and webhook surfaces are activated from the compiled surface dispatch plans in the bundle. Adding a new surface means adding to wiring.surfaces in the spec.
  • Your scenario suite is your test suite. runScenarios({ spec, bundle }) exercises the same runtime with memory-backed providers. No additional test infrastructure is needed.
  • Provider swapping without code changes. Swapping from a development provider to a production provider means updating the lockfile and redeploying. The spec and application code do not change.

The three-call arc​

The three calls map directly to the three developer moments:

CallWhen it runsWhat it does
defineApp()Author timeValidates the spec against GooiAppSpec@1.0.0
compileApp()Build / CIProduces the CompiledEntrypointBundle
createAppRuntime()Deploy / startupActivates providers and boots the kernel

defineApp() never compiles. compileApp() never executes. createAppRuntime() never reads the raw spec.

What's next​

  • Ecosystem: bind real providers to your compiled artifact
  • Scenarios: run your spec's behavioral tests against the L3 runtime
  • Installation: full package reference