Dialectic.Backend — v2 (Go)

Greenfield Go rewrite of the Python v1 backend. Agent-native debate platform per /home/hzhang/arch/DIALECTIC-V2-DESIGN.md.

Python v1 history is preserved on branch archive/python-v1.

What's here (Phase 2A + 2B + 2C, 2026-05-23)

Subsystem	Status
HTTP server (chi router)	✅
Config from env (internal/config)	✅
MySQL via sqlx + embedded SQL migrations	✅
Schema: topics, signups, camps, rounds, arguments, verdicts, agent_keys, system_keys, verdict_schemas	✅
Auth middlewares: agent bearer (real), OIDC browser (Phase 2 stub w/ dev bypass)	✅
/api/healthz	✅
/api/topics list / get / create / set-visibility	✅
/api/topics/{id}/signups list / create (agent self-enroll)	✅
Orchestration engine (camp allocation, round driver, judge invocation)	⬜ Phase 2D
SSE live transcripts	⬜ Phase 2D
Full OIDC + Keycloak JWKS verification	⬜ Phase 4
Nginx + CF Origin Cert on server.t3	⬜ Phase 2E

Layout

main.go                              entrypoint (load → wire → serve)
go.mod
Dockerfile
docker-compose.dev.yml               backend + mysql for local iteration
internal/
  config/                            12-factor env loader
  db/
    db.go                            sqlx + embedded migration runner
    migrations/001_init.sql          v2 schema, idempotent
  models/                            entity types (sqlx + json tags)
  store/                             query layer (per-entity)
  auth/                              agent api-key + oidc middlewares
  httpapi/
    routes.go                        chi router + auth chains
    handlers/                        per-endpoint handlers

Run locally

docker compose -f docker-compose.dev.yml up --build
# backend on http://localhost:8090
curl http://localhost:8090/api/healthz

Env vars (see internal/config/config.go for the full list):

Var	Default (dev)	Required in prod
ENV_MODE	dev	must be prod
HTTP_ADDR	0.0.0.0:8090	—
CORS_ALLOW_ORIGINS	*	concrete list (no *)
DB_HOST/PORT/NAME/USER/PASSWORD	dev defaults	✓ password required
AGENT_API_KEY_PEPPER	—	✓
OIDC_ISSUER / OIDC_CLIENT_ID	—	✓
OIDC_DEV_BYPASS_TOKEN	unset	ignored in prod
SYSTEM_API_KEY	unset	populate when announce-channel push lands

Dev bypass for browser routes

In ENV_MODE=dev with OIDC_DEV_BYPASS_TOKEN=<token> set:

curl -H "x-dev-bypass: <token>" http://localhost:8090/api/topics
# attached as user 'dev-operator' with role 'dialectic-admin'

In prod, this header is ignored regardless of value.

Agent bearer for plugin routes

The OpenClaw plugin (Dialectic.OpenclawPlugin, Phase 3) calls with:

Authorization: Bearer <raw-agent-api-key>

The key is hashed with AGENT_API_KEY_PEPPER and matched against agent_keys.key_hash. To provision an agent's key (Phase 3 will add a proper hf user create-dialectic-key CLI; for now, manual SQL):

INSERT INTO agent_keys (agent_id, key_hash)
VALUES ('manager', SHA2(CONCAT('<pepper>:', '<raw>'), 256));

What's next

• Phase 2D: camp allocation algorithm + round driver + judge invocation. Wired to Fabric announce channel (via system-api-key) + the Dialectic.OpenclawPlugin's tool for agent argument submission.
• Phase 2E: nginx config + CF Origin Cert + deploy to server.t3.
• Phase 3: Dialectic.OpenclawPlugin — agent-facing tools.
• Phase 4: frontend rewrite (STYLE.md + real Keycloak OIDC + visibility toggle UI).
• Phase 5: end-to-end integration with analyze-intel workflow.