Model governance outcomes before they happen. The Vote Simulator is an interactive scenario-planning tool for NEAR Protocol's House of Stake governance body. It pulls live on-chain delegate data and lets you simulate how proposals will play out under different voting rules, delegate behaviors, and strategic conditions.
The core of the app. Build named scenarios, adjust parameters, and see projected outcomes in real time:
- Scenario management — create, duplicate, rename, compare, and export scenarios
- Voting rules — toggle between supermajority (67%) and simple majority (>50%), bundle or individual proposal mode
- Per-delegate predictions — engine-generated predictions with manual overrides and optional AI analysis
- Synthetic actors — add hypothetical delegates to model "what if" scenarios
- veNEAR adjustments — model changes to delegate voting power
- Strategic analysis — procedural & legitimacy risk scoring across four dimensions (Interpretation, Precedent, Narrative, Retry Clarity)
- Scenario comparison — side-by-side evaluation of multiple scenarios with projected outcomes
- Export — PDF (print-ready A4 landscape), Excel spreadsheet, and JSON workspace import/export
Browse all veNEAR delegates with voting history, participation rates, and power distribution.
On-chain proposal data with vote breakdowns, thresholds, outcomes, and per-delegate drill-down.
All data is sourced from on-chain records — never fabricated or mocked.
| Source | What |
|---|---|
| Agora Governance API | Proposals, delegate rosters, vote records |
NEAR RPC (venear.dao) |
veNEAR balances via ft_balance_of |
| NearBlocks | Transaction explorer links |
- Next.js 16 — App Router, Server Components, Cache Components
- React 19 — with TanStack Query for data management
- Zustand — client-side state for simulator scenarios
- Tailwind CSS + shadcn/ui — UI components
- Zod — runtime API response validation
- ExcelJS + react-to-print — export capabilities
- Node.js >= 20
- pnpm 10.x
- Docker Engine + Docker Compose v2 (for container deployment)
git clone https://github.com/HackHumanityOrg/hos-intel.git
cd hos-intel
pnpm install
cp command-center/.env.example command-center/.env
pnpm devOpen http://localhost:3333.
Copy the example env file and fill in values as needed:
cp command-center/.env.example command-center/.env| Variable | Required | Description |
|---|---|---|
NEXT_PUBLIC_APP_URL |
Yes | Canonical app URL and OpenRouter referer header |
NEXT_PUBLIC_AGORA_ENV |
No | Upstream governance API environment (prod, staging, dev, local) |
NEXT_PUBLIC_NAV_PAGES |
No | Comma-separated nav ids to expose in the UI |
ANTHROPIC_API_KEY |
No | Enables AI-assisted vote analysis |
OPENAI_API_KEY |
No | Fallback AI provider |
OPENROUTER_API_KEY |
No | Alternative AI provider |
AI_PROVIDER, AI_MODEL |
No | Explicit AI provider/model override |
The simulator works fully without any API keys — AI analysis is an optional enhancement.
pnpm dev # Start dev server on :3333
pnpm build # Production build
pnpm start # Start production server
pnpm lint # TypeScript checking
pnpm typecheck # TypeScript checking
pnpm test # Run Vitest unit tests
pnpm test:e2e # Run Playwright e2e tests
pnpm format:check # Prettier format check
pnpm docker:build # Build Docker image
pnpm docker:up # Start with Docker Compose
pnpm docker:down # Stop Docker Compose
pnpm health # Check /healthz endpoint
pnpm deploy:check # Full pre-deploy quality gateAll root scripts are thin wrappers around the command-center app.
pnpm docker:build
docker run --rm \
--name hos-command-center \
-p 3333:3333 \
--env-file command-center/.env \
hos-command-center
pnpm healthThe image uses Next.js standalone output, runs as a non-root user, and honors PORT and HOSTNAME at runtime.
cp command-center/.env.example command-center/.env
pnpm docker:up
docker compose logs -f command-center
pnpm health
pnpm docker:downpnpm build
HOSTNAME=0.0.0.0 PORT=3333 node command-center/.next/standalone/command-center/server.jshos-intel/
command-center/ # Next.js application
Dockerfile # Production image build
src/
app/
simulator/ # Vote Simulator (main feature)
delegates/ # Delegate directory & profiles
proposals/ # Proposal explorer & vote breakdowns
api/ # Route handlers (AI analysis, governance data)
healthz/ # Health check endpoint
components/ # UI components (shadcn/ui + custom)
lib/ # Data fetching, prediction engine, utilities
e2e/ # Playwright end-to-end tests
docker-compose.yml # Local single-service deployment
scripts/ # Secret scanning, git hooks
docs/screenshots/ # README assets
A pre-commit hook (installed automatically via pnpm install) scans staged files for accidentally committed secrets, API keys, and connection strings.
Contributions welcome. Please open an issue first to discuss what you'd like to change.
- Fork the repo
- Create a feature branch (
git checkout -b feature/my-change) - Make your changes and run
pnpm deploy:check - Open a pull request
MIT — Created by Hack Humanity