Skip to content

candpixie/yhack-commons

BranchesTags

Repository files navigation

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

  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.

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

  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.

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.

Further reading

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)

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

About

yhack-eight.vercel.app

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages