From 0a6dd03e91565bf0a6a8f10d3cf484ad890a32385d535ae7d7a97fc0fc7a6a57 Mon Sep 17 00:00:00 2001 From: Tyler J King Date: Sat, 18 Apr 2026 07:23:08 -0400 Subject: [PATCH] docs: README, runtime config, CI placeholder 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) Signed-off-by: Tyler J King --- .forgejo/workflows/.gitkeep | 1 + README.md | 131 +++++++++++++++++++++++++++++++++++- 2 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 .forgejo/workflows/.gitkeep diff --git a/.forgejo/workflows/.gitkeep b/.forgejo/workflows/.gitkeep new file mode 100644 index 0000000..70c256a --- /dev/null +++ b/.forgejo/workflows/.gitkeep @@ -0,0 +1 @@ +# Placeholder for Forgejo CI workflows (WS2 follow-up) diff --git a/README.md b/README.md index 2f80cf2..5213558 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,133 @@ # Guildhall -**TODO: Add description** +**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: + +- — governance dashboard +- — open ceremonies +- — 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.