commons

Turn neighborhood noise into coordinated action.

AI-assisted community coordination for mutual aid, safety, and resources — map-first reporting, trust-weighted matching, live local news, municipal-ready analytics, and a background integrity layer governments can trust.

**Built at YHack 2026 **

The Problem

Neighborhoods run on goodwill and spreadsheets, not a shared operating picture.

Fragmented signals — Food needs, safety concerns, and infrastructure issues live in group chats, 311 tickets, and org silos; no single prioritization layer.
Late visibility — Critical issues surface only after escalation or harm; residents lack a common urgency language.
Matching is manual — Connecting surplus food, volunteers, and needs depends on who knows whom, not transparent scoring.
Weak accountability — Stakeholders can’t easily show what was decided, when, and why to funders or city partners.

“We get twenty messages a day. I don’t know which block to prioritize first — or who already stepped up.” — Community organizer (illustrative)

The Solution

Commune gives neighborhoods a single coordination stack:

Report on a map → Urgency + trust scoring → Smart matches → Health + integrity signals for residents and gov

Report — Pin issues on an interactive map (Crown Heights–style demo geography); optional live news ties to “report related issue.”
Score — Deterministic urgency rules plus structured reasoning objects (weights, explanations, hashes).
Coordinate — Match engine connects needs, resources, and volunteers with transparent factor breakdowns.
Trust & verify — Contribution history and trust scores; Solana devnet memos anchor high-value events in the background (no wallet UX). K2 Think V2 explains consequences and anchor context in plain language.

One demo neighborhood. One stack. Map + metrics + optional Hex analytics runtime.

Key Features

Map & live local news

Full-view MapLibre map with teardrop pins, urgency styling, and pull-up urgent list.
Server-Sent Events for live news ingestion; diamond markers and popups with AI-generated community impact (K2) where configured.
Dedicated News split-screen: map + scrolling feed, filters, “Report related issue” deep link.

Reporting & issues

Report flow with fullscreen click-to-place location picker.
Issue detail: category, urgency label, people affected, “if no action by tonight” consequence copy from K2 Think V2.
Status updates, verification, escalation, volunteer hooks via API.

Matching & trust

Weighted match scoring (proximity, urgency, availability, resource fit, completion probability).
3-layer reasoning — structured JSON, canonical hash, natural-language summary; visible in UI drawers.
Trust scores from behavior: account age, completed actions, follow-through, org verification, recent activity.

Community health

Rolling health metrics (issues resolved, response time, volunteers, food security index, safety score, trust network) with trends and evidence-style copy.
Scheduled health snapshots with reasoning blobs for demos and gov narrative.

Resources & barter

Offers and requests; exchange proposals and alignment helpers.
Optional resource chat endpoint for natural-language matching.

Gov dashboard & spatial intelligence

H3 hex aggregation: issue density, urgency mix, category breakdown, timeline of platform events.
Stat cards aligned to municipal pitch (open issues, people affected, match rate, etc.).

Hex Technologies integration

Investigation workbooks — POST /api/hex/investigation creates a Hex project and programmatic CODE cells (pandas + matplotlib) from live SQLite issue data (mock mode without token).
Community Health Briefing Engine — POST /api/hex/trigger-report runs a published Hex app with inputParams (neighborhood, time_window, optional match_id / issue_id). Auto-triggered on match confirmed/completed and issue escalate.
Gov UI — “Trigger briefing run,” “Run + poll,” links to latest run / published project when env is set.

See PLATFORM_DATA_CONTEXT.md §9b–9c and backend/.env.example for env names.

Commune AI (chat)

Tool-using agent: resources, metrics, issues, matches, alerts, submit_report, show_on_map.
show_on_map resolves issue_id, alert_id (mapped to demo issues), or match_id → coordinates returned as map_focus on POST /api/chat so the map flies to the location (and navigates to Map when needed).

Integrity layer (Solana, background)

No wallet UI — integrity is surfaced as IntegrityBadge + optional K2 explanation of anchor metadata.
Devnet Memo-style anchoring with simulation fallback so demos never hard-fail.

Architecture

┌─────────────────────┐         ┌─────────────────────┐
│   Frontend (Vite) │  HTTP   │   Backend (Express) │
│   React 18 + TS     │ ◄─────► │   TypeScript        │
│   Port 5173         │  /api   │   Port 3001         │
│   MapLibre · Motion │         │   better-sqlite3    │
└─────────────────────┘         └──────────┬──────────┘
        │                                   │
        │  SSE /api/news/stream             │  Schedulers: news poll, health snapshots
        │                                   │
        ▼                                   ▼
   Optional VITE_API_URL              SQLite (issues, matches, events,
   → remote Railway API                 resources, anchors, news, metrics)

Integrations (optional, env-driven): K2 Think V2 · OpenAI · GNews · Hex API · Solana devnet.

Tech Stack

Frontend

Technology	Purpose
React 18	UI
TypeScript	Type safety
Vite 6	Dev server & build
Tailwind CSS v4	Styling (`@tailwindcss/vite`)
Motion	Animations
MapLibre GL	Interactive map
React Router 7	Routing
Lucide React	Icons
Recharts	Charts (dashboard / health)
Radix UI + shadcn-style primitives	`ui/src/app/components/ui/*`
Sonner	Toasts

Backend

Technology	Purpose
Node.js 18+	Runtime
Express	HTTP API
TypeScript	Type safety
better-sqlite3	Embedded SQL
h3-js	Hexagonal spatial aggregation
dotenv	Configuration
cors	Cross-origin
tsx	Dev watch / seed scripts
OpenAI SDK	K2-compatible client + OpenAI models
@solana/web3.js	Devnet anchoring

AI, data & external APIs

Technology	Purpose
K2 Think V2	Chat agent, consequence text, news impact, anchor explanations (`MBZUAI-IFM/K2-Think-v2`)
OpenAI	Fallback models (e.g. gpt-4o-mini) if K2 key absent
GNews	Live article polling + geocoding
Hex	Published project runs + optional notebook CRUD
Solana devnet	Background integrity memos

Variable names only — see backend/.env.example and docs/TEAM_CREDENTIALS_DISCORD.md. Never commit real keys.

Installation & setup

Prerequisites

Node.js 18+ and npm
Git

Quick start

git clone https://github.com/candpixie/yhack.git
cd yhack

# Backend
cd backend
npm install
cp .env.example .env
# Edit .env locally — do not commit secrets
npm run seed
npm run dev
# API: http://localhost:3001

# Frontend (new terminal)
cd ../ui
npm install
npm run dev
# UI: http://localhost:5173  (proxies /api → :3001)

Teammates without backend keys

Run UI only with a shared deployed API:

cd ui
echo 'VITE_API_URL=https://YOUR-RAILWAY-OR-API-ORIGIN' > .env.local
npm run dev

Details: docs/HACKATHON_TEAM_SETUP.md.

Root scripts (optional)

cd yhack
npm run build    # installs ui + backend deps, builds both
npm run start    # seed + node backend dist (serves ui/dist when built)

Environment variables (optional, in backend/.env):

OPENAI_API_KEY — enables the platform-wide AI chatbot
NEWS_API_KEY — enables live news feed from GNews
COMMONS_SOLANA_PRIVATE_KEY — base64-encoded key for real devnet transactions
COMMONS_SOLANA_USE_SIMULATION=true — skip real transactions, use simulated hashes

Project structure

yhack/
├── backend/
│   ├── src/
│   │   ├── index.ts              # Express app, static ui/dist, route mount
│   │   ├── db.ts                 # SQLite schema
│   │   ├── seed.ts               # Demo data
│   │   ├── routes/
│   │   │   ├── issues.ts
│   │   │   ├── matches.ts
│   │   │   ├── community.ts
│   │   │   ├── resources.ts
│   │   │   ├── health.ts
│   │   │   ├── anchor.ts
│   │   │   ├── chat.ts
│   │   │   ├── news.ts
│   │   │   ├── dashboard.ts
│   │   │   └── hex.ts
│   │   └── services/             # matching, trust, urgency, agent, solana, newsFetcher, etc.
│   ├── .env.example
│   └── package.json
├── ui/
│   ├── src/
│   │   ├── app/
│   │   │   ├── App.tsx
│   │   │   ├── routes.tsx
│   │   │   ├── components/       # MapView, NewsPage, DashboardPage, ChatPanel, …
│   │   │   ├── context/          # MapFocusContext
│   │   │   └── lib/              # api.ts, mapStyle.ts
│   │   └── styles/
│   ├── vite.config.ts
│   └── package.json
├── docs/
│   ├── HACKATHON_TEAM_SETUP.md
│   └── TEAM_CREDENTIALS_DISCORD.md
├── PLATFORM_DATA_CONTEXT.md      # Data model & metrics reference
├── package.json                  # Root build/start orchestration
├── railway.toml
├── vercel.json
└── README.md

API overview

Base URL: {origin}/api (local: http://localhost:3001/api).

Area	Example endpoints	Notes
Issues	`GET/POST /issues`, `GET /issues/:id`, `PATCH .../status`, `POST .../verify`, `.../escalate`, `.../volunteer`	Reports & lifecycle
Matches	`GET /matches`, `GET /matches/:id`, `GET /matches/for-issue/:issueId`, `PATCH /matches/:id/status`	Triggers Hex briefing on confirm/complete
Community	`GET /community/alerts`, `GET /community/summary-metrics`	Alerts & summaries
Resources	`GET/POST /resources`, `PATCH .../claim`, `POST .../exchange`, `GET .../exchanges`, `POST .../chat`	Offers, requests, barter
Health	`GET /health`, `GET /health/snapshots`	Metrics & snapshots
Anchor	`GET /anchor`, `GET /anchor/:id`, `GET /anchor/explain`	Integrity + K2 explanation
Chat	`POST /chat`	`{ messages }` → `reply`, `tool_results`, optional `map_focus`
News	`GET /news/recent`, `GET /news/stream` (SSE)	GNews + seed articles
Dashboard	`GET /dashboard/hex`, `/stats`, `/timeline`	Gov analytics
Hex	`POST /hex/investigation`, `POST /hex/trigger-report`, `GET /hex/briefing`	Notebooks + briefing runs
Events	`GET /events`	Platform audit trail
System	`GET /ping`	Health check

Demo data highlights (seeded)

Illustrative numbers from the bundled seed + metrics (see PLATFORM_DATA_CONTEXT.md §10):

Metric	Demo value	Context
Issues (demo set)	6+ reports	Food, safety, infrastructure, volunteer offers
People affected (rolled up)	200+ in narrative	Pantry, school crossing, etc.
Critical open	2	Food pantry, unsafe crossing
Match success rate	82%	Shown on Gov dashboard
Avg response time	18h	Health metric storyline
Anchored records	3	Issues + match (devnet / sim)
Live news articles	8 seed + API	Brooklyn-relevant when GNews enabled

Key workflows

Report an issue — Map → Report → pick category, pin location, submit → appears on map with urgency.
Follow a match — Open match from map/issue flow → see score breakdown + integrity badge → update status (confirmed / completed triggers Hex briefing if configured).
Gov / hex track — Gov tab → adjust H3 resolution → Hex investigation or Trigger briefing run → open Hex links from panel.
Ask AI to show a case on the map — Chat: e.g. “Show alert a2 on the map” → model calls show_on_map → response includes map_focus → map flies to linked issue (e.g. Dean St / PS 221 scenario).
Integrity — Issue or match detail → expand Integrity → optional K2 explanation of anchor + metadata.

Design system (tokens)

From ui/src/styles/theme.css (light shell):

Token	Role
`--commune-bg-primary`	`#FAFAF8` — page background
`--commune-bg-secondary`	`#F2F0EB` — panels
`--commune-text-primary`	`#1A1917` — primary text
`--commune-text-secondary`	`#6B6860` — secondary
`--commune-blue`	`#2563EB` — links / accents
`--commune-red`	`#DC2626` — critical urgency
`--commune-amber`	`#D97706` — urgent
`--commune-green`	`#16A34A` — low / positive
`--commune-map-base`	`#E8E0CC` — map chrome

Urgency labels drive pin colors and dashboard semantics (critical → urgent → moderate → low).

Deployment

Railway (full stack)

railway.toml: Nixpacks installs root + ui + backend, builds both, starts cd backend && npm run seed && node dist/index.js.
Set DB_PATH to a persistent path (e.g. /data/commune.db) and mount a volume — otherwise SQLite resets on redeploy.
Inject secrets via Railway variables (same names as .env.example).

Vercel (frontend only)

Root directory (important): In the Vercel project → Settings → General → Root Directory:
- Leave empty (repository root) → uses vercel.json at repo root (cd ui && npm ci + ui/dist).
- Or set to ui → uses ui/vercel.json (npm ci in ui/, output dist). Do not use the root vercel.json pattern with Root Directory = ui (that would run cd ui from inside ui/ and fail).
Set VITE_API_URL to your Railway (or other) API origin (no trailing slash).
Optional: VITE_CLERK_PUBLISHABLE_KEY for Clerk; if unset, email/password demo login uses defaults from ui/.env.example.

SDG alignment

SDG 8 — Local coordination and micro-opportunities (volunteers, exchanges).
SDG 9 — Resilient community infrastructure for information and trust.
SDG 11 — Safer, more inclusive neighborhoods through shared visibility and response.

Built with

react · typescript · vite · tailwindcss · motion · maplibre-gl · react-router · recharts · lucide-react · sonner · express · better-sqlite3 · h3-js · openai · @solana/web3.js

Team

Built at YHack 2026 — Commune team (add names / roles as you like).

License

No LICENSE file is present in this repository root yet. Add one (e.g. MIT, Apache-2.0, or hackathon-specific terms) before public distribution.

Acknowledgments

YHack 2026 organizers, mentors, and sponsors.
MBZUAI / IFM for K2 Think V2 access and documentation.
Hex Technologies for the public API and hackathon track framing.
OpenStreetMap / MapLibre contributors for map tiles and tooling.
Crown Heights neighbors and mutual-aid groups who inspire coordination-first design.

Every unresolved need is a coordination failure. Commune turns neighborhood signal into shared action.

Questions or issues? Open a GitHub issue on candpixie/yhack. Also on yhackynot.study

Name		Name	Last commit message	Last commit date
backend		backend
docs		docs
ui		ui
.gitignore		.gitignore
PLATFORM_DATA_CONTEXT.md		PLATFORM_DATA_CONTEXT.md
README.md		README.md
hex_report.png		hex_report.png
package-lock.json		package-lock.json
package.json		package.json
railway.toml		railway.toml
vercel.json		vercel.json

Doc	Purpose
PLATFORM_DATA_CONTEXT.md	Tables, metrics, scoring, gov pitch numbers
docs/HACKATHON_TEAM_SETUP.md	Teammates + `VITE_API_URL`
docs/TEAM_CREDENTIALS_DISCORD.md	Env variable reference (no secrets)

Latest commit

History

Folders and files

Repository files navigation