UzVoice Survey Platform

A comprehensive survey platform with Telegram bot integration, built with Next.js, Prisma, and PostgreSQL. This platform allows administrators to create surveys and questions, while users can participate via a Telegram bot. The web interface provides detailed analytics with pie charts and demographic breakdowns.

Features

🤖 Telegram Bot

• User registration with demographic information (name, age, gender, region)
• Interactive survey participation with targeted questions
• Questions automatically filtered based on user demographics
• Multiple choice questions with inline keyboards
• Progress tracking through surveys
• Direct database integration (no API calls for answers)

🖥️ Web Interface

• Analytics Dashboard: View survey results with interactive pie charts
• Admin Panel: Complete CRUD operations for topics and questions
• Question Targeting: Create questions for specific demographics (age, gender, region)
• Auto-Notifications: Automatically send new questions to targeted users via Telegram
• User Management: View and filter users by demographics
• Real-time Data: Live updates of survey responses
• Security: Authentication, rate limiting, input validation, CSRF protection

📊 Analytics

• Pie charts for answer distribution
• Demographic breakdowns (by gender, age groups, regions)
• Response tracking and statistics
• Export capabilities

Technology Stack

• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• Backend: Next.js API Routes, Prisma ORM
• Database: PostgreSQL
• Charts: Recharts
• Bot: node-telegram-bot-api
• Styling: Tailwind CSS with dark mode support
• Dev Tools: Biome (linting/formatting), TypeScript

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL database
• Telegram Bot Token (from @BotFather)

Installation

1. Clone and Install

   git clone <repository-url>
   cd library
   npm install

2. Environment Setup Copy .env.example to .env and configure:

   DATABASE_URL="postgresql://user:password@host:port/database"
   TELEGRAM_BOT_TOKEN="your_telegram_bot_token_here"

3. Database Setup

   # Run database migrations
   npm run db:migrate
   
   # Generate Prisma client
   npm run db:generate
   
   # Seed initial data (optional)
   npm run seed

4. Create Admin User

   # Create the first admin user
   npm run create-admin

5. Development

   # Start the web application
   npm run dev
   
   # Start the Telegram bot (in another terminal)
   npm run bot

6. Production

   # Build the application
   npm run build
   
   # Start both web app and bot together
   npm start

   Open http://localhost:3000 to view the web interface.

Usage

Web Interface

1. Analytics Dashboard (/)

   • View all topics and their questions
   • Select questions to see detailed analytics
   • Interactive pie charts show answer distributions
   • Demographic breakdowns available

2. Admin Panel (/admin)

   • Topics Tab: Create, view, and delete survey topics
   • Questions Tab: Add questions with multiple options to topics
   • Users Tab: View registered users and apply demographic filters

Telegram Bot

1. Registration

   • Send /start to begin registration
   • Provide name, age, gender, and region
   • Registration is required before participating

2. Surveys

   • Send /surveys to see available topics
   • Select a topic to start answering questions
   • Navigate through questions with inline keyboards
   • Receive completion confirmation

API Endpoints

• GET/POST /api/topics - Topics management
• GET/PUT/DELETE /api/topics/[id] - Individual topic operations
• POST /api/questions - Create questions
• GET/PUT/DELETE /api/questions/[id] - Question operations
• GET /api/questions/[id]/analytics - Question analytics
• GET/POST /api/users - User operations (with filtering)
• POST /api/answers - Submit answers

Database Schema

Users

• tgId (String, Primary Key): Telegram user ID
• name (String): User's full name
• gender (String): "male" or "female"
• region (String): Uzbekistan region
• age (Int): User's age

Topics

• id (Int, Auto-increment): Topic ID
• name (String, Unique): Topic name
• questions[]: Related questions

Questions

• id (Int, Auto-increment): Question ID
• name (String): Question text
• options (String[]): Array of answer options
• topicId (Int): Foreign key to Topic
• targetGender (String, Optional): Target gender ("male"/"female" or null for all)
• targetMinAge (Int, Optional): Minimum age for targeting
• targetMaxAge (Int, Optional): Maximum age for targeting
• targetRegions (String[], Optional): Array of target regions

Answers

• id (Int, Auto-increment): Answer ID
• option (String): Selected option
• questionId (Int): Foreign key to Question
• userTgId (String): Foreign key to User
• Unique constraint on (questionId, userTgId)

Scripts

# Development
npm run dev          # Start Next.js development server
npm run bot          # Start Telegram bot

# Database
npm run db:migrate   # Run Prisma migrations
npm run db:generate  # Generate Prisma client
npm run db:studio    # Open Prisma Studio
npm run seed         # Seed initial data

# Production
npm run build        # Build for production
npm start            # Start both web app and Telegram bot
npm run start:web    # Start only web app
npm run start:bot    # Start only Telegram bot

# Code Quality
npm run lint         # Check code with Biome
npm run format       # Format code with Biome

Project Structure

src/
├── app/
│   ├── api/                 # Next.js API routes
│   │   ├── topics/         # Topic CRUD operations
│   │   ├── questions/      # Question CRUD operations
│   │   ├── users/          # User management
│   │   └── answers/        # Answer submissions
│   ├── admin/              # Admin panel page
│   ├── globals.css         # Global styles
│   ├── layout.tsx          # Root layout
│   └── page.tsx            # Analytics dashboard
├── bot/
│   └── telegram-bot.ts     # Telegram bot implementation
├── components/
│   └── PieChart.tsx        # Reusable chart component
├── lib/
│   ├── prisma.ts           # Prisma client setup
│   └── database.ts         # Database service functions
prisma/
├── schema.prisma           # Database schema
└── migrations/             # Database migrations
scripts/
└── seed.ts                 # Database seeding script

Deployment

Vercel (Web App)

1. Connect your repository to Vercel
2. Add environment variables in Vercel dashboard
3. Deploy automatically on push

Railway/Render (Bot)

1. Create a new service
2. Connect repository
3. Set build command: npm install && npm run db:generate
4. Set start command: npm run bot
5. Add environment variables

Database

• Use managed PostgreSQL from Vercel, Railway, or Supabase
• Update DATABASE_URL in environment variables

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run npm run lint and npm run format
5. Submit a pull request

License

MIT License - see LICENSE file for details.