arbiter

Platform Design — Phase 5 Infrastructure

Design specs for features requiring deployment infrastructure. Code is buildable; deployment needs human action (account setup, DNS, secrets).

---

A: Arbiter Cloud (REST API)

What: Hosted scoring API — POST /score with a GitHub URL, get a score back.

Architecture:

Client → Arbiter API (Cloudflare Workers or Fly.io)
           ├── Clone repo (shallow, temp)
           ├── Run analyzers
           ├── Return JSON score
           └── Record in audit trail

Endpoints:

• POST /v1/score — score a repo by URL
• POST /v1/certify — full certification
• GET /v1/leaderboard — current leaderboard
• GET /v1/health — service health

Auth: API key in X-Arbiter-Key header. Free tier: 10 scores/day. Paid: unlimited.

Deployment: arbiter serve already exists. Wrap in Dockerfile, deploy to Fly.io.

Human action needed:

• Create Fly.io account or Cloudflare Workers project
• Set up domain: api.hummbl.io or arbiter.hummbl.io
• Configure secrets: GITHUB_TOKEN for cloning

---

B: GitHub App

What: Install on an org → automatic PR quality checks on every push.

How it works:

1. PR opened → GitHub sends webhook to Arbiter API
2. Arbiter clones the PR branch
3. Runs arbiter diff --base main
4. Posts score as PR check + comment
5. Fails the check if below threshold

App manifest (register at github.com/settings/apps/new):

name: HUMMBL Arbiter
description: Deterministic code quality scoring
url: https://hummbl.io/audit
webhook_url: https://api.hummbl.io/github/webhook
permissions:
  checks: write
  pull_requests: write
  contents: read
events:
  - pull_request

Human action needed:

• Register GitHub App at github.com/settings/apps
• Set webhook secret
• Deploy webhook receiver (part of Arbiter Cloud API)
• Create installation flow page on hummbl.io

---

C: Dashboard

What: Web UI showing fleet scores, trends, team leaderboard.

Architecture: Static HTML generated by arbiter leaderboard --html + weekly GitHub Action. For v1, no backend needed — just static files served from GitHub Pages or hummbl.io.

Pages:

• /leaderboard — top repos by quality score (generated weekly)
• /repo/:name — individual repo score card (future)
• /certify — certification status page (future)

Human action needed:

• Add GitHub Pages to arbiter repo, or
• Deploy to hummbl.io/audit subdirectory
• Wire weekly Action to push generated HTML

---

Implementation Order

1. PyPI package (this PR) — enables pip install arbiter-score
2. Leaderboard HTML (parallel PR) — static page ready to deploy
3. Webhooks (parallel PR) — notification module
4. Arbiter Cloud — after PyPI is live, wrap serve in Docker
5. GitHub App — after Cloud API is live
6. Dashboard — leaderboard HTML is v1; expand later

---

Powered by HUMMBL — governed AI for enterprise.

This site is open source. Improve this page.