VENI-AIDOCS
03 / Develop · Veni builder · Overview

Veni builder ​

Veni builder is the platform's dev-tooling app. It runs as a Shell remote (and standalone) and does three jobs: it serves the veni CLI and hosts the New remote app wizard — the two ways to scaffold a new satellite — and hosts a component catalog for the shared UI primitives. It's a Make-driven repo with a Bun API (:3010) and a Vite UI (:3011).

What Veni builder does ​

Three jobs, all aimed at getting a new app off the ground:

  • Serves the veni CLI — the API hosts the one-line installer and the CLI tarball, so curl … | bash gives you the binary that scaffolds and registers apps (Install the CLI).
  • Hosts the scaffold wizard — the "New remote app" flow generates a full satellite (API + UI + Shell auth + federation) in the browser, the no-CLI path (Scaffold).
  • Hosts the component catalog — a browsable registry of the shared UI primitives, generated from its own themed UI and shipped to satellites via veni add or the API (Components).

Unlike the Shell, Veni builder is stateless — no database. It reads the filesystem, the vendored app-template, and the component registry; there's nothing to persist. The full surface is on the API page.

The moving parts ​

What it isRuns at
APIServes the veni CLI install script + the dev-only scaffold endpoints:3010
UIComponent catalog (path: /components) + the Scaffold form (path: /):3011
Vendorapp-template (scaffold skeleton) + draft-registry (catalog of theme components + blocks)

The component catalog is always on. The Scaffold feature — which writes files and shells out to the veni CLI — is gated to development (configure it).

Architecture ​

Like the Shell and every satellite, the API is a Bun + Hono + Ignis app — but stateless: it persists nothing and operates on files in the repo. The API and the UI are the two entry points; both work through vendor/. The three highlighted boxes are the repo's top-level trees — everything else is a module or a file they own:

Three flows do the work:

  • Distribute the CLI — cli.controller → builder.service.packageCli() bundles the CLI scripts + app-template + draft-registry + the scaffolder module + capabilities.json into a tarball; install.sh drops it into ~/.local/bin. The veni binary a developer installs is this toolchain. → The CLI
  • Scaffold — services/scaffolder.ts copies app-template, token-replaces the placeholders, and applies the database recipe on --db. The same code runs whether the CLI invokes it locally or builder.controller's dev-only POST /scaffold does. → Scaffold
  • Sync the registry — the UI owns the themes and their components and blocks; sync-registry emits a JSON file per item into draft-registry, which is what the catalog and veni add serve. → Components

So the progressive veni enable capabilities live here (capabilities.json + the scaffolder's recipe), not in the generated apps — you extend the CLI by editing these.

The codebase ​

Two trees — a Bun API and a Vite UI — plus the vendored sources they operate on.

API — api/src/ ​

text
api/src/
├─ application.ts   # BuilderApplication — the composition root
├─ controllers/     # cli (install) · builder (scaffold, dev-gated) · registry · auth · openapi
├─ services/        # scaffolder · builder.service (packageCli) · asset-resolver · registry
├─ assets/          # the veni CLI as source — bundled & served, not run here
├─ strategies/      # request auth: jwt · pat
└─ grpc/            # Connect services (the UI/CLI mostly use /api)

UI — ui/src/ ​

text
ui/src/
├─ main.tsx                # entry — the UI is itself a Shell remote
├─ federation/             # exposes ./ShellEntry so the Shell can mount it
├─ pages/ · features/      # the component catalog + the New-remote-app wizard
├─ components/             # UI primitives used across the builder
├─ docs/                   # theme demos + their source components (VENI · VelaUI)
└─ themes/                 # CSS + Tailwind config for the builder UI

The vendored sources ​

text
vendor/
├─ app-template/    # the skeleton every scaffold copies from — edit to change what `veni create` produces
└─ draft-registry/  # the component catalog the UI + AI agents read

Next ​

  • Run — clone, configure, and run the API + UI.
  • Install the CLI — the one-line installer for the veni binary.
  • Scaffold — generate a satellite with the wizard or veni create.
  • API — the endpoints (CLI install, scaffold, registry) + the live openapi.json.
  • Build a satellite — take a scaffolded app all the way: DB, auth, integration, shipping.