Pharos Spec

Pharos is a shared runtime and build system for declarative web apps. This page summarizes the framework contract: hosting profiles, authoring boundary, generated surfaces, persistence model, and operational behavior.

App model

Two hosting profiles are supported today:

• Dynamic Apps — server-rendered apps with native request handling, templates, generated surfaces, and database-backed state
• Static Apps — fully materialized static content delivered as built artifacts

The shipped dynamic_app and static_app projects are reference apps for these two profiles. Their tutorial and authoring guidance live in the Tutorial; this page only describes the framework contract they exercise.

Declarative boundary

Apps declare structure and behavior in files. The framework owns execution.

Pharos uses YAML (.yml) as the sole authoring format for supported declarative app surfaces. The build pipeline emits normalized JSON artifacts for the runtime; source JSON is not an input format.

App-owned files:

• pharos.app.yml — canonical app manifest source
• pharos.app.json — built artifact manifest contract
• fixtures/ and data/ — YAML or JSON route, surface, workflow, policy, and app data declarations
• templates/ — HTML templates and fragments, plus supported declarative YAML page sources where applicable
• static/ and media/ — shipped assets
• app.conf — local configuration overrides
• src/ — generated-admin composition metadata

Framework-owned:

• Request parsing and dispatch
• Rendering behavior
• Generated admin and API surfaces
• Validation, coercion, and relation checks
• Policy and tenant scoping
• Workflow and action execution
• Payment-provider account, callback, checkout, webhook, and audit execution
• Audit and effect recording
• Packaging and artifact layout
• Health, liveness, readiness, backup, restore, and deploy checks
• Multi-app hosting

Build and distribution targets

The native build and packaging toolchain currently targets:

• Linux x86_64 (GNU and musl)
• Linux ARM64 (GNU)
• Linux RISC-V (GNU)
• macOS x86_64 and macOS arm64 as separate distribution targets
• Windows x86_64 (MSVC)
• Windows ARM64 (MSVC)
• wasm32-wasi artifact packaging

Build model

Apps build into a predictable directory layout at <build-dir>/apps/<app_id>/.

The build process:

• Loads declarative source with YAML-first precedence
• Compiles supported YAML source into normalized JSON artifacts
• Copies fixtures, templates, and assets
• Emits runtime metadata
• Validates artifact structure

The resulting artifact is the deployment surface used for local serving, packaged release builds, and shared-runtime hosting.

Hosting model

Multiple apps can run under one shared runtime process. Each app mounts at a distinct base path. The runtime handles transport, routing, logging, and health checks for all apps.

Generated surfaces

Pharos generates the following surfaces from fixture declarations:

• Admin CRUD pages such as manage, create, edit, update, and delete
• API CRUD endpoints
• Declarative action contracts with typed inputs and response contracts
• Workflow execution tied to actions, including multi-step approval
• Framework-owned job, webhook, and notification execution
• Audit-event emission for writes and workflow activity

Generated surfaces are rendered by the native runtime from fixture data, not from per-app controller code.

Data and persistence model

Dynamic apps are database-driven by default. The configured database backend is the source of truth. Runtime scratch JSON files may exist as operational surfaces but are not authoritative.

Supported database backends:

• SQLite
• PostgreSQL
• MySQL
• MongoDB

Redis is available as an optional runtime cache layer. It is not authoritative state and does not replace the selected database backend.

Payment-provider model

Apps can opt into a reusable payment-provider interface through app-owned declarations. The initial provider implementation is Stripe, including provider account connection, encrypted credential storage, callback nonce validation, checkout-mode control, Stripe-hosted Checkout Sessions, signed webhook confirmation, and payment-state transitions for success, expiration, failure, refund, and dispute events.

Apps own the provider policy gate, owner-resource mapping, checkout action, return paths, and presentation templates. The runtime owns provider requests, secret redaction, durable provider state, callback validation, webhook handling, audit events, and fulfillment gating.

Operational model

Pharos provides:

• TCP and Unix-socket serving
• Health, liveness, readiness, and version probes
• Shared request logging and error reporting
• Backup and restore workflows
• Deploy validation and drift checks
• Config resolution through shared runtime config plus app-local overrides