Pharos Architect

Pharos Architect is the authenticated webapp interface for the local-first Pharos model-driven app builder. It lets an operator describe a new app, attach supporting context, run the built-in no-cloud builder path or a tested active external LLM vendor, inspect generated evidence, preview the generated app, and download a verified source bundle for local save.

Architect is a model-driven builder because the center of the workflow is the app model: requested routes, actions, entities, UI archetypes, validation expectations, acceptance criteria, and export rules. The builder converts that model into app-owned Pharos source, runs local validation, and writes evidence files that make the result reviewable.

The Architect app lives in apps/architect/. Its browser interface is app-owned: routes, actions, policies, templates, fragments, CSS, and progressive JavaScript are declared in that app bundle. Rust owns the execution boundaries that should not live in templates: multipart ingestion, bounded extraction, transcript persistence, queued worker processing, encrypted vault operations, source export verification, and runtime lifecycle validation.

stateDiagram-v2
    [*] --> Ready
    Ready --> Queued: create builder task
    Queued --> SavingContext: optional file or voice upload
    SavingContext --> Running: automatic build starts
    Queued --> Running: text-only automatic build starts
    Running --> Generated: app model and bounded diff ready
    Generated --> Validating: plan applied automatically
    Validating --> Completed: build verify seed doctor passed
    Running --> Blocked: missing policy, secret, or evidence
    Running --> Failed: terminal error
    Queued --> Cancelled
    Running --> Cancelled
    Completed --> Exported: source bundle requested

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

Builder workflow

An Architect task starts with direct text, an optional context file, optional voice input, or a combination of those inputs. The app stores raw uploaded bytes outside the immutable app bundle and exposes only bounded, redacted context to the builder task. Text, ZIP, DOCX, text-stream PDF, and similar source/context uploads are extracted into bounded task context before automatic synthesis. Encrypted, malformed, scanned-image, and OCR-only PDFs fail closed until local OCR support exists. When the selected LLM vendor is the built-in local builder, audio is saved as reviewable context for manual transcript entry. When the selected LLM vendor is a tested active external LLM vendor with transcription support, the audio upload is sent through the same vault, egress, and redaction boundary, the returned transcript is persisted, and the task brief is updated from that transcript before automatic build. Whisper-compatible audio vendors are transcription-only: they can support audio intake without becoming app-model generation choices.

The local builder is the required standalone path and is always available. It does not require LLM vendor credentials, cloud egress, or network access. The Create builder task action queues the task, saves any selected file or voice attachment, synthesizes an app model, scaffolds a Pharos-shaped review workspace, creates and applies a plan-digest transaction, runs local build, verify, seed, and doctor validation in an isolated output root, writes the generated source to runtime-generated storage, and enables a verified source-bundle download.

ChatGPT account controls

In Settings, select ChatGPT account under Third-party LLM integration. Connect starts provider consent; the same control becomes Disconnect while connected, or Cancel sign-in while authorization is pending. Disconnect retains the account selection. Delete saved info removes retained account information and credentials so the next connection can select another account or workspace. Test connection checks the provider using the current grant, bypassing cached model information, without generating an app.

Generated evidence

Generated apps include README.md, ACCEPTANCE.md, and BUILD-EVIDENCE.json alongside the app source. These files are part of the builder contract. They describe what was generated, which acceptance criteria the builder expects a reviewer to check, which routes/actions/entities/templates were created, which validation steps ran, and whether the source export stayed clean of databases, runtime state, uploaded context files, transcripts, vault paths, credentials, and secrets.

This evidence keeps the builder honest. A generated app is stronger when the review can prove more than source creation: the route opens, the UI is coherent, forms submit through declared actions, records persist when persistence was requested, auth and policy language is visible for protected flows, and the exported source bundle contains only app source and documentation.

Access and roles

Architect separates task authorship, settings administration, source export, and release preparation through app-owned policy roles. A normal local seed grants the demo Architect account all required roles so the smoke test can prove the whole browser flow. The local seeded username is architect and the local seeded password is pass; production deployments should replace seeded credentials and assign only the roles needed by each operator.

Release preparation records validation and release-bundle intent. Deployment transports and scaled container rollout are owned by deployment operations rather than the generated app source.

Preview sign-in

Architect prepares admin / pass and user / pass in each isolated authenticated app preview. admin receives the app's declared administrator/owner role; user receives its regular-user/customer role. Existing preview accounts remain available: apps without seeded accounts also have owner1 and customer1, and an editable copy of Architect retains architect and build. Existing previews receive the named defaults when opened without resetting established passwords or changing existing account roles. If a reserved username already belongs to an incompatible role, preparation rejects the conflict rather than elevating that account. These defaults belong only to the isolated preview database and are excluded from app source exports. Preview login details are documented here rather than displayed in the editor menu bar.

Safety model

Architect rejects path traversal, source-tree vault paths, stale plans, unsupported LLM vendors without egress authority, oversized inputs, invalid sessions, missing CSRF tokens, and unsafe rendered markup. It checks and redacts extracted context before adding it to the task. Source exports are verified by digest and expiration before download and reject database, runtime state, customer media, and secret contamination.