Impact Relay

Donation fund-use transparency and impact notification infrastructure.

Impact Relay connects a donation to its approved allocation, connects that allocation to actual expenditures, and connects those expenditures to verified programs and outcomes. Donors receive clear, consent-aware receipts explaining both what their money was used for and what that use subsequently enabled.

AI proposes. Deterministic services validate. Authorized humans approve. The ledger records. Receipts preserve lineage.

Live public tracker · Vision · Agent contract · Architecture · Durable quickstart · Hacker Dojo integration · Roadmap · Execution backlog

Why Impact Relay

Most donation products stop at payment confirmation. Accounting systems know what was purchased, program systems know what occurred, and communication systems send updates—but donors rarely receive a trustworthy, attributable explanation of the complete chain.

Impact Relay produces two linked artifacts:

Use-of-funds receipt — what was purchased or paid for, the approved amount, allocation, attribution method, date, vendor, evidence, and remaining designated balance.
Impact receipt — what the approved expenditure or funded asset later enabled, such as a verified community class, equipment deployment, or program milestone.

Example

$1,000 donation
→ Community Hardware Fund
→ $720 robotics-kit purchase approved by finance
→ donor receives use-of-funds receipt
→ kits used in a verified community class
→ donor receives impact receipt
→ later refund produces a visible correction receipt

For pooled funds, Impact Relay explains that a donation contributed to the fund supporting an expenditure. It never claims that specific dollars purchased a specific item unless direct restricted attribution is verifiable.

Product principles

Financial truth is append-only after approval.
Donation allocations cannot exceed cleared funds.
Restricted allocation balances cannot become negative.
Attribution is explicit, versioned, and reproducible.
AI may collect evidence and propose actions; it may not approve financial claims.
Use-of-funds and impact receipts remain distinct but linked.
Published corrections preserve the original receipt and full lineage.
Public exports contain no donor PII or individual gift records.
Synthetic and fixture data can never be labeled OBSERVED.

See ENGINEERING_PRINCIPLES.md.

Current maturity

Package version: 0.5.0 (capability gates through v0.7 library + pilot host path are implemented; live production ops remain open).

Current state: reusable multi-tenant Python library with durable SQLite/Postgres workflows, L0–L3 agent contracts, donor and finance console APIs, S3-capable object storage ports, and a Hacker Dojo host bridge (static screens + Supabase role mapping). Public Pages stay fixture/aggregate-only until authorized OBSERVED aggregates are applied. Ops remaining: execute live cohort and fill FINDINGS; production IdP JWT validation and live notification credentials stay host-owned.

Shipped capabilities

Capability	Module / surface
Donation, allocation, expense, attribution ledger	`src/impact_relay/domain/ledger.py`
Append-only correction and receipt lineage	domain + `workflows/corrections.py`
Programs, funded assets, impact receipts	`src/impact_relay/domain/impact.py`
Donor balances, timeline, receipt detail API	`domain/donor_views.py` · `donor/`
Consent, preferences, fixture delivery adapters	`domain/notifications.py` · `notifications/`
Multi-organization domain isolation	`domain/tenant.py` · `storage/tenants.py`
Agent contracts L0–L3, Privacy Sentinel, simulation	`src/impact_relay/agents/`
Expense intake → human approval → UOF slice	`agents/expense_workflow.py` · HD-IR-007
Durable workflows (memory + SQLite/Postgres)	`workflows/` · DURABLE-QUICKSTART
Ledger command log rehydrate (K11/K17)	`domain/ledger_log.py` · `storage/command_log.py`
Tenant registry, SQL ledger entities, outbox	`storage/` · STORAGE
Object storage (local FS + S3/MinIO)	`storage/objects.py`
RBAC roles, SoD, OIDC ports, HD role map	`auth/`
Host façade + finance/donor consoles	`host/` · `console_server.py`
Hacker Dojo canonical pilot / clone template	`storage/template.py` · integration
Aggregate public tracker and privacy-safe exports	GitHub Pages + `data/`
Every.org aggregate and Notion public-evidence bridges	CLI adapters and runbooks
Ops threat model, runbooks, pilot findings template	`docs/ops/` · `docs/pilot/`

Deferred / host-owned production capabilities

live accounting provider adapter (beyond fixture batch);
production Every.org donation ingestion (aggregate dry-run path exists);
production multi-region workflow DR and full observability (pilot local+SQL path shipped);
live OIDC JWT validation inside the library (host IdP SDK validates; ports + fixture mapper shipped);
production email / push / SMS credentials (adapters + fixture delivery shipped);
human finance live-cohort execution and findings fill (runbooks ready);
self-service multi-nonprofit onboarding UI (clone-from-Hacker-Dojo template API shipped).

Governed agentic architecture

Agents operate above the deterministic domain. They prepare evidence and proposals; they do not become an alternate ledger.

Donation and accounting providers
        │
        ▼
Provider adapters
        │ normalized records
        ▼
Agent workflow layer  (+ durable WorkflowStore)
        │ proposals, evidence checks, review packets
        ▼
Human approval gates  (console API / host UI / CLI)
        │ approved commands + ApprovalReceipt
        ▼
Deterministic domain services
        │ ledger events and canonical receipts
        ▼
Donor projections, host APIs, notification adapters

Initial agent topology

Orchestrator
Donation Intake
Expense Intake
Allocation Classifier
Evidence Validator
Finance Review
Attribution
Use-of-Funds Receipt
Asset and Program Linkage
Impact Verification
Impact Receipt
Consent and Preference
Notification Composer
Delivery
Correction and Retraction
Privacy Sentinel
Audit and Provenance

Consequential actions require independently authenticated human approval. Full contracts and authority rules are defined in AGENTS.md.

First production workflow

HD-IR-007 ships the fixture-backed core of the vertical slice (through ledger commit + optional UOF publish). Durable pilot and host console extend the same path:

fixture or accounting expense          ✅
→ allocation proposal                  ✅
→ evidence validation                  ✅
→ finance approval (ApprovalReceipt)   ✅ CLI / console / host UI
→ durable wait / worker advance        ✅
→ ledger commit + entity snapshot      ✅
→ donor attribution + UOF receipt      ✅
→ email preview                        ✅
→ independent send approval            ✅
→ fixture delivery receipt             ✅

# Demo the agent vertical slice
python -m impact_relay --expense-approval-slice
python -m impact_relay --expense-approval-slice --no-approve
python -m impact_relay --expense-approval-slice --simulate-agents
python -m impact_relay --expense-approval-slice --send-email

# Easy durable pilot (SQLite under --data-dir)
python -m impact_relay --durable seed
python -m impact_relay --durable list
python -m impact_relay --durable approve
python -m impact_relay --durable check
python -m impact_relay --durable status

# Synthetic shadow checklist (library path; not live-cohort sign-off)
python -m impact_relay --shadow-rehearsal --data-dir .impact-relay/shadow-rehearsal

# Validate a live Every.org aggregate without writing (path must not be under fixtures/)
python -m impact_relay --validate-every-org-aggregate ~/private/every_org_live.json
./scripts/apply_live_every_org_aggregate.sh --dry-run ~/private/every_org_live.json

See docs/HD-IR-007.md, docs/DURABLE-QUICKSTART.md, and docs/EVERYORG-AGGREGATE-RUNBOOK.md.

Host apps (Hacker Dojo canonical)

Impact Relay is a library. Hacker Dojo is the canonical host (UX, Supabase auth, campaign ops). Other nonprofits clone the same shape.

# Console API for host static pages
python -m impact_relay.console_server --data-dir .impact-relay/hacker-dojo --port 8787

from impact_relay.host import open_hacker_dojo_session
from impact_relay.host.hacker_dojo import finance_approver_fixture

with open_hacker_dojo_session(".impact-relay/hacker-dojo") as session:
    session = session.with_principal(finance_approver_fixture())
    session.seed()
    waiting = session.list_waiting()
    if waiting["cases"]:
        session.approve(workflow_id=waiting["cases"][0]["workflow_id"])

Host screens live in the sibling Hacker-Dojo repo (finance-impact.html, donor-impact.html, workspace/impact-relay-bridge.js). Full wiring: docs/HACKER-DOJO-INTEGRATION.md.

Money invariants

The existing domain enforces the regression bar:

donation allocations never exceed the cleared donation amount;
approved expense allocations sum to the expense amount;
restricted allocation remaining balance cannot go negative on approval;
verified use-of-funds receipts originate only from approved or reconciled expenses;
an attribution method is required and donor attribution cannot exceed the donation allocation;
only one live use-of-funds receipt exists per donation, expense, and allocation tuple;
corrections are append-only and prior receipts are never rewritten.

These rules outrank model output, operator convenience, and provider data.

Public tracker and privacy boundary

The GitHub Pages surface publishes aggregate campaign progress, public use-of-funds receipts, public impact outcomes, and event digests. It does not store donor names, emails, phone numbers, addresses, private notes, or individual gift records.

Allowed publicly	Prohibited publicly
Aggregate raised and committed amounts	Donor names
Aggregate donor count	Emails, phones, or addresses
Approved public expenditure summaries	Individual gift amounts
Public impact events	Private CRM or finance notes
Campaign milestones and processor deep links	Service credentials or raw invoices

Canonical aggregate state is stored in data/impact-state.json and validated against schemas/impact-state.schema.json in CI. Pilot data directories (.impact-relay/…) are local/staging only and must not be committed with PII.

Repository map

Impact-Relay/
├── README.md
├── VISION.md · AGENTS.md · ENGINEERING_PRINCIPLES.md
├── ROADMAP.md · TODO.md · SECURITY.md
├── docs/
│   ├── DURABLE-QUICKSTART.md
│   ├── HACKER-DOJO-INTEGRATION.md
│   ├── EVERYORG-AGGREGATE-RUNBOOK.md
│   ├── HD-IR-00x.md                     # milestone notes
│   ├── architecture/
│   │   ├── AGENTIC-SYSTEM.md
│   │   ├── DURABLE-WORKFLOWS.md
│   │   └── STORAGE.md
│   ├── ops/                             # threat model, runbooks, checklist
│   └── pilot/                           # HD pilot + FINDINGS template
├── src/impact_relay/
│   ├── domain/                          # ledger, impact, notifications, tenant
│   ├── agents/                          # L0–L3 contracts + expense slice
│   ├── workflows/                       # durable runtime, worker, corrections
│   ├── storage/                         # SQL store, objects, tenants, template
│   ├── auth/                            # principal, RBAC, OIDC ports, role map
│   ├── host/                            # session façade, finance/donor console
│   ├── donor/                           # donor experience API
│   ├── notifications/                   # delivery adapters
│   ├── console_server.py                # pilot HTTP API for host UIs
│   ├── pilot.py · cli.py · public_export.py
│   └── every_org.py · notion_public.py
├── policies/tenants/                    # e.g. hacker-dojo.v1.0.yaml
├── fixtures/ · schemas/ · data/
├── tests/ · scripts/
├── index.html · app.js · styles.css     # public Pages tracker
└── .github/workflows/

Architecture detail: docs/architecture/AGENTIC-SYSTEM.md, DURABLE-WORKFLOWS.md, STORAGE.md.

Setup

Requires Python 3.11+.

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# optional: pip install -e ".[db]"   # Postgres (psycopg)
# optional: pip install -e ".[s3]"   # S3/MinIO object storage
pytest

Optional Postgres pilot stack: docker compose -f docker-compose.postgres.yml up.

Pilot commands

Use-of-funds pilot:

python -m impact_relay
python -m impact_relay --fixture fixtures/pilot_hd_ir_001.json

All fixture-backed phases:

python -m impact_relay --all-phases
python -m impact_relay --all-phases --fixture fixtures/pilot_all_phases.json

Durable (default SQLite data dir):

python -m impact_relay --durable help
python -m impact_relay --durable seed --data-dir .impact-relay/hacker-dojo
python -m impact_relay --durable worker --once --data-dir .impact-relay/hacker-dojo

Library API:

from impact_relay.pilot import run_pilot, run_all_phases_pilot

ledger, receipts = run_pilot()
platform, payload = run_all_phases_pilot()

Public exports

# Privacy-safe public use-of-funds export
python -m impact_relay --write-public data/use-of-funds-public.json

# One-shot public Pages regeneration
python -m impact_relay --publish-pages

# Domain impact events to public digests
python -m impact_relay --all-phases --digests-from-domain \
  --merge-fixture-digests \
  --write-digests data/impact-digests-public.json

# Every.org-style aggregate summary
python -m impact_relay \
  --every-org-aggregate fixtures/every_org_aggregate_v1.json \
  --write-impact-state data/impact-state.json

# Notion public evidence
python -m impact_relay \
  --notion-public-evidence fixtures/notion_public_evidence_v1.json \
  --write-public-evidence data/public-evidence.json

Applying authorized live aggregates

Published totals remain raisedSource: pilot_synthetic and PILOT until finance provides an authorized aggregate file.

cp fixtures/templates/every_org_live_aggregate.template.json ~/private/every_org_live.json
# edit the private file with authorized aggregate totals only
./scripts/apply_live_every_org_aggregate.sh ~/private/every_org_live.json

The hard provenance gate rejects fixture or pilot sources when --require-observed is enabled.

Roadmap

v0.5: agent contracts, authority enforcement, policies, simulation, Privacy Sentinel — done
v0.6: expense ingestion, evidence validation, human finance review, durable pilot path — done (library)
v0.7: canonical donor use-of-funds receipts, correction workflows, donor API — done (library)
v0.8: funded assets, program verification, impact receipts — domain shipped; staff verification UI host-side
v0.9: controlled Hacker Dojo pilot (host screens + runbooks shipped; live cohort ops open)
v1.0: production Hacker Dojo deployment
v1.1: reusable multi-tenant nonprofit platform
v2.0: general impact infrastructure

See ROADMAP.md and TODO.md.

Security and contribution

Review SECURITY.md and docs/ops/ before changing donor, evidence, provider, or public-export boundaries. Agent, policy, attribution, evidence, receipt-schema, and notification-gate changes require independent review.

License

Apache-2.0. See LICENSE.

Navigation Menu

Repository files navigation

Impact Relay

Why Impact Relay

Example

Product principles

Current maturity

Shipped capabilities

Deferred / host-owned production capabilities

Governed agentic architecture

Initial agent topology

First production workflow

Host apps (Hacker Dojo canonical)

Money invariants

Public tracker and privacy boundary

Repository map

Setup

Pilot commands

Public exports

Applying authorized live aggregates

Roadmap

Security and contribution

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
.github/workflows		.github/workflows
.hallmark		.hallmark
data		data
docs		docs
fixtures		fixtures
policies/tenants		policies/tenants
schemas		schemas
scripts		scripts
src/impact_relay		src/impact_relay
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ENGINEERING_PRINCIPLES.md		ENGINEERING_PRINCIPLES.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
TODO.md		TODO.md
VISION.md		VISION.md
app.js		app.js
design.md		design.md
docker-compose.postgres.yml		docker-compose.postgres.yml
index.html		index.html
pyproject.toml		pyproject.toml
styles.css		styles.css
tokens.css		tokens.css

Folders and files

Latest commit

History

Repository files navigation

Impact Relay

Why Impact Relay

Example

Product principles

Current maturity

Shipped capabilities

Deferred / host-owned production capabilities

Governed agentic architecture

Initial agent topology

First production workflow

Host apps (Hacker Dojo canonical)

Money invariants

Public tracker and privacy boundary

Repository map

Setup

Pilot commands

Public exports

Applying authorized live aggregates

Roadmap

Security and contribution

License

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages