# Guildhall

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

`guildhall` presents and coordinates; [`substrate`](../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

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

### Run the server

```bash
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

```bash
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](../guildhouse-specs/design/DESIGN-OPS-DB-CHAIN-OF-CUSTODY-0001.md) — Ops DB schema + self-hosted FFC threat model
- [DESIGN-HFL-DB-ENFORCEMENT-0001](../guildhouse-specs/design/DESIGN-HFL-DB-ENFORCEMENT-0001.md) — BPF map ABI for DB governance
- [DESIGN-ORG-OPS-FRAMEWORK-0001](../guildhouse-specs/design/DESIGN-ORG-OPS-FRAMEWORK-0001.md) — governed full-stack framework
- [DESIGN-FORGE-WORKSPACE-0001](../guildhouse-specs/design/DESIGN-FORGE-WORKSPACE-0001.md) — governed workspace staging
- [SPEC-CEREMONY-0001](../guildhouse-specs/family/ffc-app/SPEC-CEREMONY-0001.md) — ceremony protocol

---

## License

Apache 2.0.