Claude × Penn AI Hackathon 2026 — First Place Project (Democratic Governance)
A civic empowerment platform that turns a personal grievance into a professional-grade advocacy toolkit — powered by Claude agents, ElevenLabs voice I/O, and the Cicero political-districts API.
Millions of Americans have legitimate grievances with their local, state, and federal government — and no practical way to turn that frustration into action. Writing an effective letter to your city council member, figuring out which state representative owns your issue, or drafting testimony for a public hearing takes expertise most citizens don't have time to build.
Heard closes that gap. A citizen speaks or types a grievance and provides a US address. Heard returns:
- Root cause analysis — the systemic issues driving the problem
- Affected-population estimate — how many neighbors share it
- Elected-official power map — who actually has jurisdiction, from city council to Congress
- Drafted communications — letters, testimony, and petitions ready to send
- Political strategy brief — a concrete roadmap for turning grievance into action
- Community map & feed — every public grievance plotted and searchable, so officials and journalists see what's trending in a district
- Candidate dashboard — verified elected officials see and respond to constituent grievances directed at their office
Heard ships as a full-stack web application: a multi-agent backend built on LangGraph, a REST gateway built on FastAPI, and a Next.js 16 frontend with real-time streaming, voice I/O, and an interactive MapLibre GL map.
- Key Features
- Architecture
- Quick Start
- Configuration
- Project Layout
- Development
- Deployment
- Security
- Contributing
- Acknowledgments
- License
- Multi-agent advocacy workflow — Claude-powered sub-agents research the issue, identify jurisdiction, and produce a full advocacy package.
- Cicero API integration — one-click geolocation → council / state-house / state-senate / congressional districts.
- Inline action cards — the agent emits structured "Send Now" cards inside the chat stream, each pre-filled with the right official, subject line, and body text.
- ElevenLabs voice I/O — speak your grievance (STT) and hear responses aloud (TTS).
- Civic map — public grievances plotted on MapLibre GL with severity coloring and institution markers.
- Grievance feed — full-text searchable via PostgreSQL
tsvector, sortable by recency or follower count. - Grievance detail pages — shareable permalinks with officials-contacted timeline, candidate responses, and similar issues.
- Follow & notifications — follow a grievance, get notified on milestones, status changes, or candidate replies.
- Verified dashboard — elected officials see grievances in their district with multi-level jurisdiction matching.
- District Pulse analytics — category breakdown, 12-month trend, emerging issues, resolution rate.
- Respond publicly — candidates post responses that appear on the grievance page and notify every follower.
- better-auth email+password with PostgreSQL adapter, dual user types (constituent / candidate).
- Location privacy — display coordinates drift ±0.002° from the real location.
- Email delivery — SendGrid integration with graceful console-log fallback.
- PostgreSQL persistence — users, profiles, grievances, sent actions, follows, responses, notifications.
┌──────────────────────────────────────────────────────────────────────┐
│ User (voice / text) │
└──────────────────────────────┬───────────────────────────────────────┘
│
┌──────────▼───────────┐
│ Next.js Frontend │ port 3000
│ (React 19 · TS) │
└──────────┬───────────┘
│
┌──────────▼───────────┐
│ Nginx reverse │ port 2026 ← primary entry
│ proxy │
└─────┬────────────┬───┘
│ │
┌─────────────────▼─┐ ┌───▼─────────────────┐
│ Gateway API │ │ LangGraph Server │
│ FastAPI · 8001 │ │ Agent runtime │
│ │ │ port 2024 │
│ /api/civic │ │ │
│ /api/voice │ │ lead_agent + tools │
│ /api/grievances │ │ + sub-agents │
│ /api/dashboard │ │ + skills + sandbox │
│ /api/notifications └──────────┬──────────┘
│ /api/threads │ │
└─────────┬─────────┘ ┌──────────▼──────────┐
│ │ Claude models │
│ │ (Anthropic API) │
│ └─────────────────────┘
┌─────────▼─────────┐
│ PostgreSQL │ ← users, grievances, actions,
│ (Supabase) │ follows, responses, notifications
└───────────────────┘
- Agent harness: an internal framework under
backend/packages/harness/orchestrates sub-agents, tools, memory, skills, and a sandbox. - Streaming: LangGraph SDK streams messages and tool calls to the frontend over SSE.
- Artifacts: the agent can emit files (letters, briefs,
action-cards.json) that render inline in the chat stream.
| Tool | Version |
|---|---|
| Python | 3.12+ |
| Node.js | 22+ |
| pnpm | 10.26+ |
| uv | latest |
| nginx | 1.20+ |
| PostgreSQL | 14+ (or a Supabase project) |
make check # Verify all prerequisitesgit clone https://github.com/StevenWang-CY/Heard.git
cd Heard
make installHeard uses a three-file environment system:
cp .env.example .env # shared API keys
cp .env.development.example .env.development # dev DB + auth secrets
cp .env.production.example .env.production # prod DB + auth secrets
cp config.example.yaml config.yaml # models, tools, sandbox
cp extensions_config.example.json extensions_config.json # MCP + skillsFill in at minimum:
# .env
ANTHROPIC_API_KEY=sk-ant-... # Claude
CICERO_API_KEY=... # district matching
ELEVENLABS_API_KEY=... # voice I/O
TAVILY_API_KEY=... # optional: web search
JINA_API_KEY=... # optional: web fetch
# .env.development
DATABASE_URL='postgresql://...'
AUTH_SECRET=$(openssl rand -hex 32)
BETTER_AUTH_SECRET=$AUTH_SECRETInitialize the auth tables on a fresh database:
cd frontend && npx @better-auth/cli migrate -y --config src/server/better-auth/config.tsApp migrations in backend/migrations/*.sql auto-run on gateway startup.
make dev # all services, hot-reload
# → http://localhost:2026| Command | Purpose |
|---|---|
make check |
Check system prerequisites |
make install |
Install frontend + backend dependencies |
make dev |
Start all services in development mode |
make start |
Start all services in production mode |
make stop |
Stop all services |
make doctor |
Diagnose configuration issues |
Edit config.yaml to add or swap LLM providers. Heard defaults to Claude:
models:
- name: claude-sonnet
display_name: Claude Sonnet 4.6
use: deerflow.models.claude_provider:ClaudeChatModel
model: claude-sonnet-4-6
max_tokens: 8192
supports_thinking: true
api_key: $ANTHROPIC_API_KEYOpenAI, Ollama, vLLM, OpenRouter, Groq, Together, and others are supported — see config.example.yaml for the full reference.
extensions_config.json declares MCP servers and the skills enabled for the agent runtime. Skills live under skills/ and use progressive loading (a lightweight SKILL.md is registered up front; heavy assets load on demand).
See CLAUDE.md for the full set of environment variables that toggle individual features (voice, SendGrid email, Cicero cache TTL, etc.).
Heard/
├── backend/
│ ├── app/gateway/ # FastAPI REST gateway
│ │ ├── routers/ # civic, grievances, dashboard, voice, threads
│ │ ├── services/ # elevenlabs, cicero, sendgrid
│ │ ├── cicero_service.py # district matching client
│ │ └── db.py # asyncpg pool
│ ├── packages/harness/ # agent harness (LangGraph orchestration)
│ ├── migrations/ # SQL migrations, auto-run on startup
│ └── pyproject.toml
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js App Router (App Router routes)
│ │ ├── components/ # React components (workspace, auth, ui)
│ │ ├── core/ # business logic (threads, civic, auth, i18n)
│ │ └── server/ # better-auth server config
│ └── package.json
├── skills/ # agent skills (progressive-load)
├── docker/ # docker-compose, nginx configs
├── scripts/ # setup, diagnostics, deployment
├── doc/ # reference docs (Cicero, districts)
├── config.example.yaml # model / tool / sandbox config
├── CLAUDE.md # engineering guide for AI pair-programmers
├── CONTRIBUTING.md # contributor guide
├── SECURITY.md # disclosure policy
└── README.md # you are here
cd backend
make dev # LangGraph server (port 2024)
make gateway # Gateway API (port 8001)
make test # pytest
make lint # ruffcd frontend
pnpm dev # Turbopack dev server (port 3000)
pnpm check # eslint + tsc --noEmit
pnpm build # production buildPut new SQL in backend/migrations/NNN_name.sql. The gateway runs pending migrations on startup; production deployments are safe to restart.
Heard ships with deployment blueprints for the common free/low-cost paths:
- Frontend → Vercel.
vercel.jsonis pre-configured; setDEER_FLOW_INTERNAL_GATEWAY_BASE_URLandDEER_FLOW_INTERNAL_LANGGRAPH_BASE_URLto point at your backend host. - Backend → Render.
render.yaml+Dockerfile.renderprovide a one-click Docker deploy. The single container runs both the gateway and the LangGraph server under a process supervisor. - Database → Supabase (or any managed Postgres).
Production requires:
AUTH_SECRET/BETTER_AUTH_SECRET— cryptographically random, identical on both services.CORS_ALLOWED_ORIGINS— comma-separated frontend origins.BETTER_AUTH_TRUSTED_ORIGINS— trusted origins for better-auth (Vercel preview URLs are added automatically viaVERCEL_URL/VERCEL_BRANCH_URL/VERCEL_PROJECT_PRODUCTION_URL).
See SECURITY.md for the vulnerability disclosure policy. Highlights:
.env*files are gitignored; only*.exampletemplates are tracked.- Example files contain only placeholders — no real project refs, passwords, or keys.
- Auth secrets must be regenerated before any deployment.
- The agent sandbox is intended to run in a trusted local environment by default. If you expose the gateway to the public internet, put it behind authentication and network isolation.
If you find a vulnerability, do not open a public issue. Email the maintainer (see SECURITY.md).
Contributions are welcome — see CONTRIBUTING.md for the development workflow, code style, and PR checklist. All contributors must follow the Code of Conduct.
- Claude × Penn AI Hackathon 2026 — winning entry, Democratic Governance track.
- Anthropic Claude — the reasoning engine behind every agent.
- ElevenLabs — voice I/O (STT + TTS).
- Cicero API — elected-official and political-districts data.
- DeerFlow — the open-source super-agent harness by ByteDance that Heard's multi-agent runtime builds on.
- LangChain and LangGraph — agent orchestration primitives.
- Next.js, MapLibre GL, better-auth, shadcn/ui.
MIT © Heard contributors.