guildhall/README.md

Guildhall

Ceremony orchestrator and governance UI — Elixir/Phoenix umbrella over substrate CRDs.

guildhall presents and coordinates; substrate decides and enforces. The ceremony engine is a Rust Kubernetes operator with CRDs and etcd-backed state. guildhall is the orchestrator: it coordinates humans around those CRDs — notifying witnesses, collecting signatures via LiveView, tracking status, rendering dashboards.

┌────────────────────────────────────────────────────────┐
│ SUBSTRATE (Rust, K8s operators) — decides + enforces    │
│   CeremonyEngine (CRD), AccordEvaluator (CRD),          │
│   CorpusReconciler (CRD), PostureEvaluator (CRD),       │
│   Chronicle collector (agent)                           │
└────────────────────┬───────────────────────────────────┘
                     │ watches CRDs + emits Chronicle events
                     ▼
┌────────────────────────────────────────────────────────┐
│ GUILDHALL (Elixir/Phoenix) — orchestrates + presents    │
│   CeremonyOrchestrator (workflow coordinator)           │
│   AccordComposer (UI + submission)                      │
│   ArtifactBrowser (UI + lifecycle)                      │
│   PostureDashboard (visualization)                      │
│   ChronicleConsumer (projector + UI)                    │
└────────────────────────────────────────────────────────┘

Naming discipline: guildhall components are orchestrators (workflow, coordination, presentation). The substrate components are engines and reconcilers (enforcement, state-machine advancement). Never call a guildhall component by a substrate name.

---

Umbrella apps

App	Role
guildhall_web	Phoenix LiveView UI — dashboards, ceremonies, artifacts, posture
guildhall_orchestrator	Watches substrate CRDs (future), notifies witnesses, broadcasts ceremony status over PubSub
guildhall_ops_db	Ecto schemas for the five Ops DB tables (per DESIGN-OPS-DB-CHAIN-OF-CUSTODY-0001)
guildhall_graph_bridge	Microsoft Graph API reconciler — Intune deployment (stub)
guildhall_chronicle	Chronicle event consumer + Ops DB projector (stub)

---

Local development

Prerequisites

• Elixir 1.17.x + OTP 27 (via mise or asdf)
• Postgres 14+ running on localhost:5432 with a postgres superuser (password postgres for dev)

First-time setup

mix deps.get
mix ecto.create
mix ecto.migrate
mix run apps/guildhall_ops_db/priv/repo/seeds.exs

Run the server

mix phx.server

Then visit:

• http://localhost:4000/ — governance dashboard
• http://localhost:4000/ceremonies — open ceremonies
• http://localhost:4000/artifacts — governed artifacts registry

Run tests

mix test

---

Configuration

Development defaults are in config/dev.exs (Postgres at localhost:5432 as postgres/postgres, database guildhall_dev). Production runtime configuration reads from environment variables in config/runtime.exs:

Env var	Purpose
DATABASE_URL	Postgres connection (required in prod)
SECRET_KEY_BASE	Phoenix cookie/session signing (required in prod)
PHX_HOST	Public hostname (default guildhall.guildhouse.dev)
PHX_SERVER	Set to true to run the HTTP server under mix release
POOL_SIZE	DB pool size (default 10)
ECTO_IPV6	Set to true for IPv6 DB connections

Commented placeholders exist for future sprints: KUBECONFIG (substrate CRD watcher) and OIDC_ISSUER / OIDC_CLIENT_ID / OIDC_CLIENT_SECRET (Keycloak auth).

---

Relationship to the rest of the stack

guildhall is one of the PaaS components (ROADMAP WS1). It sits alongside:

• substrate — the governance Rust crates + K8s operators
• bxnet-ops — the org-ops CLI framework (reference fork: BXNet)
• guildhouse-mcp — MCP server for LLM mediator context
• guildhouse-specs — the FFC specifications

See the design docs for the full picture:

• DESIGN-OPS-DB-CHAIN-OF-CUSTODY-0001 — Ops DB schema + self-hosted FFC threat model
• DESIGN-HFL-DB-ENFORCEMENT-0001 — BPF map ABI for DB governance
• DESIGN-ORG-OPS-FRAMEWORK-0001 — governed full-stack framework
• DESIGN-FORGE-WORKSPACE-0001 — governed workspace staging
• SPEC-CEREMONY-0001 — ceremony protocol

---

License

Apache 2.0.