Tyler J King
0a6dd03e91
README explains: - guildhall = ceremony orchestrator + governance UI - guildhall != ceremony engine (that's substrate) - five umbrella apps with responsibilities - local dev setup (mix deps.get + ecto.setup + phx.server) - runtime config env vars (DATABASE_URL, SECRET_KEY_BASE, PHX_HOST, POOL_SIZE, ECTO_IPV6) - relationship to substrate, bxnet-ops, guildhouse-specs - links to all relevant design docs .forgejo/workflows/ placeholder for CI (future WS2 work). Runtime config (config/runtime.exs) reads DATABASE_URL with ECTO_IPV6 socket option support. Commented placeholders for KUBECONFIG (substrate CRD watcher) and OIDC_* (Keycloak) are explicit about what comes in future sprints. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Signed-off-by: Tyler J King <tking@guildhouse.dev>
133 lines
5.1 KiB
Markdown
133 lines
5.1 KiB
Markdown
# 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.
|