Pharos Framework

← Back

Pharos Spec

Pharos Framework is a declarative web application framework and shared multi-app host.

It is built for teams that want to author app structure in checked files while relying on one shared runtime for request handling, rendering, packaging, health checks, deployment behavior, logging, and other cross-cutting runtime concerns.

Core product claim

Pharos aims to give teams one coherent platform for:

  • server-first web applications
  • packaged app artifacts
  • static and dynamic app hosting
  • shared runtime operations
  • database-backed dynamic apps
  • declarative app authoring

The practical claim is not that Pharos invents a new app theory. The practical claim is that app teams can ship powerful web apps while keeping more of their app definition in app-owned declarative files and less of their runtime behavior in per-app glue code.

Why build this

Most web teams eventually accumulate too much duplicated runtime work across apps.

Common failure modes include:

  • every app rebuilds the same hosting and packaging assumptions
  • request-path behavior drifts between apps
  • operational behavior such as logging, health, or CSRF is implemented inconsistently
  • deployable artifacts are unclear or ad hoc
  • app bundles mix product content with runtime mechanics

Pharos exists to centralize those runtime and operational concerns once so app authors can focus more on product behavior and less on infrastructure repetition.

Current app model

Pharos currently supports two main hosting profiles:

1. static-pages

For apps that can ship as materialized artifacts.

Typical characteristics:

  • packaged HTML and assets
  • app-local docs or content sites
  • static delivery through the shared runtime
  • predictable artifact directories

2. dynamic-app

For apps that need runtime request handling, templates, generated surfaces, and relational persistence.

Typical characteristics:

  • native runtime request handling
  • declarative app manifests, templates, and fixtures
  • shared runtime protections and logging
  • SQLite or PostgreSQL backing stores
  • packageable app artifacts and runtime metadata

Declarative app boundary

Pharos is designed so the app boundary stays as declarative as practical.

App-owned surfaces usually include:

  • pharos.app.json
  • route, surface, workflow, and related fixtures
  • templates and fragments
  • static and media assets
  • seed data and app content
  • app.conf overrides

Framework-owned runtime behavior includes:

  • request parsing and routing behavior
  • rendering semantics
  • listener and connection handling
  • database/runtime coordination
  • shared logging and error reporting
  • CSRF and shared runtime protections
  • health, readiness, backup, and restore behavior
  • packaging and deployment validation

Packaging model

Pharos builds apps into predictable artifact directories.

A packaged app may include:

  • pharos.app.json
  • app.conf
  • start.sh
  • checked fixture files
  • templates, static assets, and media
  • compiled host artifacts where required
  • runtime companion metadata

The packaging goal is that operators and developers can inspect what was built and understand how the app is expected to run.

Hosting model

Pharos is meant to host multiple apps behind one shared runtime.

That model includes:

  • app discovery from app bundles
  • per-app base paths such as /ucal and /dev_docs
  • shared runtime transport behavior
  • shared logging and health reporting
  • consistent app packaging and runtime metadata

This makes Pharos especially suitable for teams that operate several related server-rendered apps, internal tools, and support surfaces together.

Data and persistence model

Dynamic apps are database-driven by default.

Current supported relational backends are:

  • SQLite
  • PostgreSQL

Runtime scratch JSON exports may exist for operational reasons, but they are not the primary source of truth when the relational backend is active.

Generated and framework-owned surfaces

Pharos already exposes framework-owned generated behavior where that improves consistency.

Current supported business-logic scaffolding includes:

  • generated admin-style CRUD surfaces
  • generated API CRUD surfaces
  • checked route and surface fixtures
  • shared validation and coercion
  • shared authorization and tenant-scope enforcement
  • native runtime request handling
  • packaging and runtime metadata emission
  • shared helper behavior that should not be duplicated per app

The framework is currently strongest when business behavior fits this generated CRUD model. Public product claims should describe that implemented scope clearly.

Operational requirements

Pharos should provide a usable production posture for:

  • health and readiness probes
  • shared logging and error reporting
  • backup and restore workflows
  • deploy validation
  • packaged Unix-socket or TCP serving
  • predictable runtime config handling

What Pharos must be good at

The platform should be strong at:

  • authoring declarative server-first apps
  • hosting multiple apps together
  • packaging inspectable app artifacts
  • keeping runtime ownership centralized in the framework
  • supporting dynamic apps without pushing operators into app-specific runtime glue

Non-goals for the public product story

The public Pharos product story should not rely on outdated experimental framing.

It should not describe the framework primarily as:

  • a speculative research system
  • a graph database product
  • a speculative decision engine
  • an unfinished platform theory

The public story should describe what Pharos currently is: a declarative app framework, a shared multi-app host, and a native runtime and packaging surface.