🎯 PickOne

Create a poll. Share it. See what people pick.

A fast, beautiful social voting platform where you create quick polls and share them with anyone. No registration required.

---

✨ Features

Feature	Description
⚡ Instant Polls	Create a poll in seconds — no sign-up needed
🔗 Shareable Links	Every poll gets a unique URL you can share anywhere
📊 Live Results	Watch votes come in real-time via WebSocket
🛡️ Duplicate Protection	SHA-256 fingerprint prevents double-voting
🖼️ Image Options	Add images to poll choices (auto-resized & converted to WebP)
🎨 Dark Mode	Beautiful dark/light theme with system preference detection
📱 Responsive	Looks great on phones, tablets, and desktops
📤 Social Sharing	Share to Telegram, WhatsApp, X, or copy link / QR code
🔐 Creator Controls	Edit, close, or delete your polls with a secure token
📈 Statistics	Poll creators can view detailed voting analytics

---

📸 Screenshots

Create a Poll

Live Results

---

🛠️ Tech Stack

Frontend

• React 19 + TypeScript — Type-safe UI components
• Vite — Lightning-fast build tool
• Tailwind CSS v4 — Utility-first styling
• TanStack Query v5 — Server state management
• React Router v7 — Client-side routing
• Framer Motion — Smooth animations
• Lucide React — Beautiful icons
• Recharts — Data visualization
• qrcode.react — QR code generation

Backend

• Python 3.12+ with FastAPI — High-performance async API
• SQLAlchemy 2.0 — Async ORM with proper type support
• Pydantic v2 — Data validation
• Alembic — Database migrations
• Pillow — Image processing
• WebSockets — Real-time updates

Infrastructure

• PostgreSQL 16 — Production database
• SQLite — Local development (zero setup)
• Docker & Docker Compose — Containerized deployment
• Nginx — Reverse proxy with gzip & security headers

---

🚀 Quick Start

Local Development (Recommended)

1. Clone the repository:

git clone https://github.com/rezvvent/pickone.git
cd pickone

2. Start the backend:

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

3. Start the frontend (new terminal):

cd frontend
npm install
npm run dev

4. Open http://localhost:5173

💡 The backend uses SQLite by default for local development — no database setup needed!

---

Docker (Production)

# Copy environment variables
cp .env.example .env

# Start all services
docker compose up --build

Open http://localhost — done!

---

📡 API Reference

Polls

Method	Endpoint	Description
POST	/api/v1/polls	Create a new poll
GET	/api/v1/polls/{slug}	Get poll details
PATCH	/api/v1/polls/{slug}	Update poll (creator only)
DELETE	/api/v1/polls/{slug}	Delete poll (creator only)
POST	/api/v1/polls/{slug}/vote	Cast a vote
POST	/api/v1/polls/{slug}/close	Close voting (creator only)
GET	/api/v1/polls/{slug}/statistics	View analytics (creator only)

Discovery

Method	Endpoint	Description
GET	/api/v1/polls/popular	Trending polls
GET	/api/v1/polls/recent	Latest polls
GET	/api/v1/polls/category/{name}	Browse by category

Real-Time

Protocol	Endpoint	Description
WS	/api/v1/ws/polls/{slug}	Live vote updates

Interactive API docs available at /api/docs when the server is running.

---

📁 Project Structure

pickone/
├── frontend/                # React + TypeScript + Vite
│   ├── src/
│   │   ├── api/             # Axios client & API functions
│   │   ├── components/      # Reusable UI components
│   │   ├── hooks/           # Custom React hooks
│   │   ├── layouts/         # Page layouts
│   │   ├── pages/           # Route pages (6 pages)
│   │   ├── types/           # TypeScript interfaces
│   │   └── utils/           # Helper functions
│   └── package.json
│
├── backend/                 # FastAPI + SQLAlchemy
│   ├── app/
│   │   ├── api/             # Route handlers & WebSocket
│   │   ├── core/            # Config, security, exceptions
│   │   ├── models/          # Database models
│   │   ├── repositories/    # Data access layer
│   │   ├── schemas/         # Pydantic schemas
│   │   └── services/        # Business logic
│   ├── alembic/             # Database migrations
│   ├── tests/               # Pytest test suite
│   └── requirements.txt
│
├── nginx/                   # Reverse proxy config
├── docker-compose.yml
└── README.md

---

🔒 Security

• No raw IPs stored — IPs are SHA-256 hashed before storage
• Creator tokens — Generated with secrets.token_urlsafe(32), stored as SHA-256 hashes
• Vote fingerprinting — SHA-256(poll_id + browser_id + hashed_ip + user_agent + salt)
• Input validation — Pydantic v2 with strict type checking
• SQL injection protection — SQLAlchemy ORM parameterized queries
• CORS — Configurable per environment
• Rate limiting — SlowAPI on all endpoints
• Image validation — MIME type, file size, and extension checks
• Security headers — HSTS, X-Frame-Options, X-Content-Type-Options via Nginx

Found a vulnerability? Please read our Security Policy for responsible disclosure.

---

🧪 Testing

# Backend tests
cd backend && source venv/bin/activate
pytest -v

# Frontend type check & build
cd frontend
npx tsc -b --noEmit
npm run build

---

📋 Environment Variables

Variable	Default	Description
DATABASE_URL	sqlite+aiosqlite:///./pickone.db	Database connection string
APP_SECRET	supersecretkey...	Secret for hashing (change in prod!)
CORS_ORIGINS	["http://localhost:5173"]	Allowed CORS origins
UPLOAD_DIR	uploads	Image upload directory
MAX_UPLOAD_SIZE	5242880	Max upload size in bytes (5MB)

See .env.example for a complete reference.

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on:

• Setting up your development environment
• Our commit message conventions
• The pull request process

---

📄 License

This project is licensed under the MIT License.

---

Built with ❤️ using React, FastAPI, and too much coffee.

Report Bug · Request Feature · Contributing