Ryan Schultz
37b5eb4609
Defines how platform weights are set and changed: founding vote (initiator defines eligible members, averaged proposals), annual community vote (all platforms simultaneously, median of submitted distributions), and structural change tier. Updates ADR 002 and ADR 007 to reflect the new mechanism, and ARCHITECTURE.md to mark weight governance as resolved rather than a future direction. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
135 lines
6.2 KiB
Markdown
135 lines
6.2 KiB
Markdown
# 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](005-git-native-voting-system.md).
|
|
|
|
---
|
|
|
|
## 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](005-git-native-voting-system.md) 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](008-platform-weight-governance.md). 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
|