Architecture Overview

Favn is a thin host that composes independently published feature artifacts at runtime.

Mental model

At runtime, the host:

1. Discovers feature artifacts from local directories and/or a remote CDN index
2. Verifies every manifest and release index cryptographically before use
3. Renders a browser shell that loads domain feature code dynamically per request and exposes facet features via SDK registry
4. Executes server functions either in-process (module mode) or via proxy (endpoint mode)
5. Delegates business authorization to feature teams — the host enforces transport, authentication, and integrity

Trust boundaries

Boundary	What it protects
Signed data	Manifests and release indexes must have valid Ed25519 signatures
Asset integrity	Every declared JS/CSS must match its SHA-256 SRI hash
Auth boundary	RPC and API calls pass through auth middleware before feature logic
Runtime permissions	Shell wraps event bus/store/lifecycle using manifest-declared permissions

Repository layout

Path	Role
apps/host	Host server (Hono), shell renderer, auth, RPC, API proxy, startup loaders
examples/*	Canonical feature implementations used as executable reference and test fixtures
shared/*	Shared runtime and build libraries (feature-sdk, schema/signing/tools, event bus/store, Vite plugin)
artifacts/*	Built and signed publish output consumed by host at runtime
scripts/*	Build/release/dev orchestration (doctor, release-workflow, create-feature, dev-server)
tests/*	Contract, security, integration, browser, and remote-CDN verification

Workspace wiring

• pnpm-workspace.yaml: apps/*, examples/*, shared/*
• turbo.json:
  • build depends on upstream ^build
  • publish:local depends on build (non-cached)
  • dev is persistent and non-cached

Root scripts

Script	What it does
pnpm run favn	Interactive developer workflow (dev/publish)
pnpm run flow	Compatibility alias for pnpm run favn
pnpm run publish -- --feature <id>	Primary developer publish command for one feature
pnpm run channel:fallback -- --feature <id> --version <x.y.z> --to <stable|canary|rollback>	Explicit fallback for channel/rollback (Admin UI is primary)
pnpm start	Validates port, builds workspace, publishes locally, starts host
pnpm run dev:host	Host with local dev defaults (hot refresh, trust-cluster mode)
pnpm run dev:feature <dir>	Standalone feature dev server with mock host APIs
pnpm run doctor	Verifies signatures, integrity, and route conflicts in artifacts
pnpm run release:{canary|promote|rollback}	Signed release index workflow