Voting Services API

A standalone Hono-powered API for Farcaster community voting and member management. Originally extracted from a Next.js application to enable reuse across multiple applications and AI agents.

🚀 Quick Start

Prerequisites

• Bun runtime
• PostgreSQL database
• Neynar API key

Installation

# Install dependencies
bun install

# Set up environment
cp .env.example .env
# Edit .env with your configuration

# Start database
bun run db:up

# Run migrations
bun run db:migrate

# Start development server
bun run dev

Server starts at: http://localhost:3000

📁 Project Structure

src/
├── index.ts              # Main Hono app
├── routes/               # API route handlers
│   ├── health.ts         # Health check endpoint
│   ├── users.ts          # User management
│   ├── members.ts        # Community members
│   ├── proposals.ts      # Proposal CRUD
│   ├── votes.ts          # Voting system
│   └── activity.ts       # Activity feeds
├── middleware/
│   └── auth.ts           # Multi-modal authentication
├── lib/
│   ├── db.ts            # VotingService integration
│   └── neynar.ts        # Neynar API client
└── db/
    ├── connection.ts     # Database connection
    ├── voting-schema.ts  # Database schema
    └── services/         # Business logic
        └── voting-service.ts

🔗 API Endpoints

Public

• GET /health - Health check

Protected (/api/v1/)

• GET /users/me - Current user info
• POST /users/lookup - Username/FID lookup
• GET /users/verifications - User verifications
• GET /members - List community members
• GET /members/status - Member status check
• GET /proposals - List proposals
• POST /proposals - Submit proposal
• GET /proposals/:id - Proposal details
• GET /proposals/current-user - User's assigned votes
• POST /votes - Cast vote
• GET /votes/current-user - User's voting history
• GET /activity - Recent activity feed

🔐 Authentication (WIP)

This API supports three authentication methods for different client types:

1. Frame SDK Tokens (Next.js Mini App users)
2. API Keys (Eliza agents, external services)
3. Service Tokens (MCP servers, internal services)

🎯 Supported Clients

Next.js Mini App

• Status: ✅ Seamless migration from embedded API routes
• Auth: Frame SDK tokens (Bearer <token>)
• Usage: Real users voting and proposing via Farcaster

Eliza AI Agents

• Status: ✅ Service key authentication
• Auth: Bearer tokens (Bearer <secret>)
• Usage: Agents submitting proposals on behalf of users

MCP Servers

• Status: ✅ Internal service tokens
• Auth: Service tokens (Service <secret>)
• Usage: AI context and comprehensive data access

🛠️ Development Scripts

# Development
bun run dev              # Start dev server with hot reload

# Database
bun run db:up            # Start PostgreSQL container
bun run db:down          # Stop PostgreSQL container
bun run db:generate      # Generate Drizzle migrations
bun run db:migrate       # Run migrations
bun run db:studio        # Open Drizzle Studio

# Production
bun run build            # Build for production
bun run start            # Start production server

🏗️ Architecture

• Runtime: Bun
• Framework: Hono (Web Standards)
• Database: PostgreSQL with pgvector
• ORM: Drizzle ORM
• Validation: Zod
• Authentication: Multi-modal (Frame SDK, Bearer tokens for services)

📊 Core Features

• Member Management: Add, remove, opt-out community members
• Proposal System: Submit and vote on member proposals
• Voting Mechanics: 3-of-5 subgroup voting with time limits
• Activity Tracking: Comprehensive audit trail
• Multi-Client Support: Works with web apps, AI agents, and MCP servers
• Performance: Fast Hono routing with connection pooling
• Type Safety: Full TypeScript coverage

🔧 Configuration

Key environment variables:

DATABASE_URL=postgresql://postgres:postgres@localhost:5555/postgres
NEYNAR_API_KEY=your-neynar-api-key
ELIZA_AGENT_SECRET=your-eliza-secret
MCP_SERVICE_SECRET=your-mcp-secret

🚀 Deployment

This API can be deployed to multiple platforms:

• Node.js servers
• Cloudflare Workers
• AWS Lambda
• Vercel/Netlify
• Any platform supporting Web Standards

📝 Migration Notes

If migrating from the embedded Next.js version:

1. Update API_URL in your client applications
2. Implement Frame SDK token verification in src/middleware/auth.ts
3. Set up authentication secrets for agents/MCP servers

All existing client code should work unchanged!

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

MIT