Architect App Builder tutorial

Use Architect when you want the Pharos model-driven app builder to create a local app from a short product brief and optional context. It turns structured intent into a Pharos app model, applies bounded source changes, validates the result, and packages reviewable evidence.

Architect is the fastest tutorial path because it shows the full Pharos app contract in one loop: routes, actions, persistence, templates, policy, generated source, validation evidence, preview, and source export.

What Architect creates

A generated app includes normal Pharos app source and generated review files:

app-owned route, action, entity, template, CSS, and metadata files
README.md describing the generated app in product language
ACCEPTANCE.md listing the generated acceptance criteria and manual review notes
BUILD-EVIDENCE.json recording the app model digest, routes, actions, entities, UI archetypes, validation expectations, export cleanliness, and unresolved items

The evidence files give the builder a definition of done beyond “files were generated.” A useful generated app should load through its declared route, submit forms through declared actions, persist records, refresh coherently, respect auth and policy boundaries, build cleanly, and export without runtime state or secrets.

Run the local smoke

scripts/check.sh architect local-smoke

The smoke builds the Architect app from local source, applies and seeds its SQLite schema in a temp tree, starts the shared runtime on loopback, signs in as the seeded local Architect user, submits a task, uploads text/audio context, checks automatic acceptance of extracted context and transcripts, runs automatic plan/apply/build/verify/seed/doctor through the browser task route, checks generated source on disk, activates loopback OpenAI-compatible, Ollama-compatible, Anthropic Claude, Google Gemini, NVIDIA NIM, and Whisper-compatible LLM vendor examples, proves external text routing, transcription-only audio routing, redacted failure fragments, and revoke behavior, prepares a release bundle, downloads a source export, and checks adversarial cases.

Run the standalone builder CLI

mkdir -p tmp/architect-demo
cat > tmp/architect-demo/task.txt <<'TASK'
Create a simple notes webapp with a dashboard and a form for new notes.
TASK
bin/pharos agent run --provider builtin --app-id notes_builder_demo --task-file tmp/architect-demo/task.txt --output-root tmp/architect-demo/out

The generated app source is written under tmp/architect-demo/out/apps/notes_builder_demo, and validation artifacts are written under tmp/architect-demo/out/dist. The command returns a JSON report with the app model, plan digest, applied files, and build, verify, seed, and doctor results. Inspect tmp/architect-demo/out/apps/notes_builder_demo/ACCEPTANCE.md and tmp/architect-demo/out/apps/notes_builder_demo/BUILD-EVIDENCE.json before treating the generated app as ready for product review.

Use the webapp

Start from the Architect dashboard. For a local seeded development database, sign in with username architect and password pass, enter an output app id, describe the app, optionally choose a context file, including a bounded text-stream PDF, or record voice, and click Create builder task. The task route automatically creates the plan, applies the generated source edits, runs build, verify, seed, and doctor, writes the generated source to runtime-generated storage, and makes the source export available after the saved bundle has been digest-verified.

With the built-in provider, audio is saved for review and manual transcript entry. With a tested active external provider, the upload is transcribed automatically and used as builder context before automatic build. If the browser blocks the microphone or JavaScript is unavailable, use the text transcript field or file upload control instead.

The built-in builder does not need third-party AI to build the first app. If you configure an OpenAI-compatible, local Ollama-compatible, Anthropic Claude, Google Gemini, or NVIDIA NIM LLM vendor in Settings, store its vault secret, enable it, and pass the connection test, that vendor appears in the builder selector. Whisper-compatible audio vendors pass as transcription-only and stay out of the app-model selector. Revoke removes a vendor from task routing and clears the redacted secret reference.

Review before export

Before sharing a generated app, open the preview and check the generated evidence against the app behavior:

Confirm the primary route opens and shows the requested app, not raw transcript or diagnostic text.
Submit one primary form or action and confirm the UI updates with understandable feedback.
Refresh and confirm the record or state persists when the generated app requested persistence.
Read ACCEPTANCE.md and confirm unresolved items are acceptable for the app stage.
Read BUILD-EVIDENCE.json and confirm routes, actions, entities, validation expectations, and export cleanliness match what the app claims.
Download the source export only after the digest-verified bundle is available.

Canonical workflow source: docs/assets/architect-task-workflow.mmd.