Agency/docs/decisions/007-web-interaction-layer.md

ADR 007 — Web interaction layer over git backend

Date: 2026-05-12 Status: Proposed

---

Context

The Agency system is git-native by design: proposals, votes, participation data, scoring logic, and decision records all live in version-controlled files. Git provides tamper-evident history, fork-ability, and no central server requirement — properties that are hard to replicate without rebuilding a database from scratch.

But git is a poor interaction layer for non-technical participants. Submitting a proposal means opening a PR. Casting a vote means running a local script and committing a file. Reading scores means running python main.py. For communities where most members are not developers, this is a significant barrier — and it would limit adoption to communities that happen to be technically fluent, which is not the intent.

The question is whether git's role as a storage and audit layer can be preserved while replacing git as the interaction layer.

---

Decision

Git remains the canonical backend and source of truth. A web interaction layer is built on top, abstracting git operations via API. The web layer holds no data of its own.

The two layers have distinct responsibilities:

Layer	Responsibility
Git backend	Storage, history, tamper-evidence, fork-ability, audit trail
Web interaction layer	Forms, dashboards, crypto in the browser, API calls to git

Technical participants retain direct git access. Non-technical participants interact through the web layer without needing to know git exists.

---

Why other approaches were rejected

Database-backed web application The obvious alternative — build a conventional web app with a database. This would be immediately accessible to non-technical users but at significant cost: tamper-evident history would require rebuilding what git provides for free; fork-ability would be lost (forks mean separate deployments, not separate repos); the audit trail would depend on the app's own logging rather than git's cryptographic history; and whoever controls the database controls the record. This inverts the project's core properties.

Git as the only interaction layer Keeping the current state — everything via git CLI and local scripts. Workable for technical communities, but excludes the broader class of communities this system is designed to serve. A governance tool that only works for developers cannot govern a community of architects, researchers, educators, and practitioners.

Forum-based proposals and polls Using the community forum for proposals and platform polls for votes. Accessible, but not fork-friendly: different communities use different forum platforms with different features. The record lives outside git, making it harder to audit and impossible to reproduce. Already rejected as the primary mechanism in ADR 005.

---

What the web layer covers

Proposal submission A web form generates the proposal file and opens a PR in the repo via the platform API (Gitea, GitHub, or equivalent). The contributor fills out a form; a commit is created on their behalf. The proposal file is the canonical artifact; the form is just the entry point.

Voting The ring-signature cryptography from ADR 005 runs in the browser (WebAssembly or JavaScript). The voter's key is managed locally; the vote file is submitted via API. The voter interacts with a simple ballot UI; the crypto and the git commit are invisible.

Score dashboard A web view of the current participation rankings, recomputed on a regular schedule and published to the repo. Community members see scores without running anything locally. The underlying data and scoring logic remain in git — the dashboard is a read-only view.

Weight and configuration proposals Platform weight changes do not follow the standard proposal flow. They are submitted as weight distribution ballots through the periodic vote mechanism defined in ADR 008. The web layer provides a ballot UI — one slider per platform, constrained to sum to 100% — that generates and submits the ring-signed distribution file. Direct config.yaml edits for weight changes are not permitted. Other configuration changes (eligibility thresholds, vote schedule, quorum floor) follow the structural change process in ADR 008.

---

The thin centralization tradeoff

A web layer requires hosting, which reintroduces a degree of centralization. This is a real tradeoff, but a limited one:

• The web server holds no data — it reads and writes to the git repo
• If the web server goes down, the repo remains intact and fully functional
• Any community can fork the repo and point a web UI at their fork — fully independent
• The git record remains auditable independently of the web layer
• Technical participants can bypass the web layer entirely at any time

This is qualitatively different from a database-backed application. The web layer is stateless infrastructure over a git backend, not a new source of truth.

---

Progressive enhancement

The web interaction layer is not required for the system to function. The git-native workflow is the foundation; the web layer makes it accessible to a wider audience. A community can adopt Agency without a web layer and add one later. A community that loses access to the web layer does not lose its data or its governance history.

This means the git-native design must remain complete and coherent on its own. The web layer adapts to it; it does not replace it.

---

Consequences

• The web dashboard ("Web-based dashboard" on the roadmap) should be scoped to cover proposals and voting, not just score display — all three are part of the same layer
• Ring-signature tooling in src/voting/ must be designed to run both as a local CLI and in a browser context; the two share the same cryptographic logic
• A community deploying Agency needs either a git platform with an API (Gitea, GitHub, GitLab) or a self-hosted equivalent — fully offline deployments would remain CLI-only
• The web layer spec (routes, API calls, form schemas) is implementation work, not architecture — it does not require a further ADR unless a significant decision point emerges during that work