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 **

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)

Commune gives neighborhoods a single coordination stack:

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

1. Report — Pin issues on an interactive map (Crown Heights–style demo geography); optional live news ties to “report related issue.”
2. Score — Deterministic urgency rules plus structured reasoning objects (weights, explanations, hashes).
3. Coordinate — Match engine connects needs, resources, and volunteers with transparent factor breakdowns.
4. 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.

• 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.

• 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.

• 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.

• 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.

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

• 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.).

• 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.

• 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).

• 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.

┌─────────────────────┐         ┌─────────────────────┐
│   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.

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

• Node.js 18+ and npm
• Git

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)

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.

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

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

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

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

1. Report an issue — Map → Report → pick category, pin location, submit → appears on map with urgency.
2. Follow a match — Open match from map/issue flow → see score breakdown + integrity badge → update status (confirmed / completed triggers Hex briefing if configured).
3. Gov / hex track — Gov tab → adjust H3 resolution → Hex investigation or Trigger briefing run → open Hex links from panel.
4. 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).
5. Integrity — Issue or match detail → expand Integrity → optional K2 explanation of anchor + metadata.

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

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

• 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).

• 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 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.

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

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

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.

• 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