# Award Voting System - Technical Specification

## Project Overview

**Project Name**: AwardVoting
**Project Type**: Laravel Web Application with Payment Integration
**Core Functionality**: An award voting platform where voters can vote for nominees by making payments of any amount via Paystack, with comprehensive admin dashboard and vote analytics.
**Target Users**: Event organizers (admin) and voters (public users)

---

## Technology Stack

- **Framework**: Laravel 10.x
- **Database**: SQLite (development) / MySQL (production)
- **Payment Gateway**: Paystack API
- **Frontend**: Blade Templates + TailwindCSS
- **Charts**: Chart.js for vote analytics
- **Authentication**: Laravel Breeze

---

## Features Specification

### 1. Public Voting Interface

#### 1.1 Homepage
- Display active award categories
- Show list of nominees per category with images and descriptions
- Each nominee card shows: photo, name, category, current vote count (optional)
- Click on nominee to view details and vote

#### 1.2 Nominee Detail Page
- Full nominee information (photo, bio, achievements)
- Vote button that initiates Paystack payment
- Custom amount input for vote payment
- Payment modal with Paystack inline integration

#### 1.3 Payment Flow
- User enters custom vote amount (minimum ₦100)
- Paystack modal opens for payment
- On successful payment:
  - Record vote in database
  - Show success confirmation
  - Update vote count
- On failed payment:
  - Show error message
  - Allow retry

### 2. Admin Dashboard

#### 2.1 Authentication
- Separate admin login page
- Secure admin routes with middleware
- Session-based authentication

#### 2.2 Dashboard Overview
- Total votes count
- Total revenue generated
- Active categories count
- Recent transactions list

#### 2.3 Category Management
- Create new award categories
- Edit category name and description
- Toggle category active/inactive status
- Delete categories (with confirmation)

#### 2.4 Nominee Management
- Add new nominees to categories
- Edit nominee details (name, photo, bio)
- View nominee statistics
- Delete nominees

#### 2.5 Vote Analytics Dashboard
- **Charts**:
  - Bar chart: Votes per category
  - Pie chart: Revenue distribution
  - Line chart: Votes over time (daily/weekly)
  - Top performers: Top 10 nominees by votes
- **Statistics Tables**:
  - All nominees ranked by votes
  - Payment transactions list
  - Filter by date range

#### 2.6 Transaction Management
- View all payment transactions
- Transaction status (success/failed/pending)
- Payment reference verification
- Export transactions to CSV

### 3. Paystack Integration

#### 3.1 Webhook Handling
- Endpoint: `/api/paystack/webhook`
- Handle `charge.success` event
- Verify payment reference
- Record vote on successful payment
- Handle duplicate webhooks gracefully

#### 3.2 Payment Verification
- Verify payment before recording vote
- Store payment metadata
- Handle failed payments

---

## Database Schema

### Categories Table
| Column | Type | Description |
|--------|------|-------------|
| id | bigint | Primary key |
| name | string | Category name |
| description | text | Category description |
| is_active | boolean | Active status |
| created_at | timestamp | Creation date |
| updated_at | timestamp | Update date |

### Nominees Table
| Column | Type | Description |
|--------|------|-------------|
| id | bigint | Primary key |
| category_id | bigint | Foreign key |
| name | string | Nominee name |
| photo | string | Photo path |
| bio | text | Biography |
| created_at | timestamp | Creation date |
| updated_at | timestamp | Update date |

### Votes Table
| Column | Type | Description |
|--------|------|-------------|
| id | bigint | Primary key |
| nominee_id | bigint | Foreign key |
| category_id | bigint | Foreign key |
| amount | decimal | Vote amount |
| payment_reference | string | Paystack reference |
| payer_email | string | Payer email |
| status | enum | success/failed/pending |
| created_at | timestamp | Vote date |

### Users Table (Admin)
| Column | Type | Description |
|--------|------|-------------|
| id | bigint | Primary key |
| name | string | Admin name |
| email | string | Admin email |
| password | string | Hashed password |
| created_at | timestamp | Creation date |
| updated_at | timestamp | Update date |

---

## API Endpoints

### Public API
- `GET /` - Homepage
- `GET /nominee/{id}` - Nominee detail page
- `POST /api/payment/initialize` - Initialize Paystack payment
- `POST /api/paystack/webhook` - Paystack webhook handler

### Admin API
- `GET /admin/login` - Admin login page
- `POST /admin/login` - Admin login action
- `POST /admin/logout` - Admin logout
- `GET /admin/dashboard` - Dashboard overview
- `GET /admin/categories` - Categories list
- `POST /admin/categories` - Create category
- `PUT /admin/categories/{id}` - Update category
- `DELETE /admin/categories/{id}` - Delete category
- `GET /admin/nominees` - Nominees list
- `POST /admin/nominees` - Create nominee
- `PUT /admin/nominees/{id}` - Update nominee
- `DELETE /admin/nominees/{id}` - Delete nominee
- `GET /admin/analytics` - Vote analytics
- `GET /admin/transactions` - Transaction list
- `GET /admin/transactions/export` - Export to CSV

---

## UI/UX Design

### Color Palette
- **Primary**: #6366F1 (Indigo)
- **Secondary**: #8B5CF6 (Purple)
- **Accent**: #F59E0B (Amber)
- **Success**: #10B981 (Emerald)
- **Danger**: #EF4444 (Red)
- **Background**: #F8FAFC (Slate-50)
- **Card Background**: #FFFFFF
- **Text Primary**: #1E293B (Slate-800)
- **Text Secondary**: #64748B (Slate-500)

### Typography
- **Headings**: Inter (bold)
- **Body**: Inter (regular)
- **Monospace**: JetBrains Mono (for amounts)

### Layout
- Responsive grid layout
- Card-based design
- Modal overlays for voting
- Sidebar navigation for admin

---

## Acceptance Criteria

### Voter Flow
- [ ] Voter can browse categories and nominees
- [ ] Voter can click on nominee to view details
- [ ] Voter can enter custom payment amount
- [ ] Paystack modal opens for payment
- [ ] Vote is recorded on successful payment
- [ ] Confirmation shown after successful vote

### Admin Features
- [ ] Admin can login with credentials
- [ ] Admin can manage categories (CRUD)
- [ ] Admin can manage nominees (CRUD)
- [ ] Dashboard shows summary statistics
- [ ] Analytics page shows charts and data
- [ ] Admin can export transactions

### Payment Integration
- [ ] Paystack payment works correctly
- [ ] Webhook handles successful payments
- [ ] Duplicate webhook events handled
- [ ] Payment verification works
- [ ] Failed payments are recorded

### Security
- [ ] Admin routes protected by auth
- [ ] CSRF protection on all forms
- [ ] Input validation on all endpoints
- [ ] Payment reference verification

---

## Configuration

### Environment Variables
```
APP_NAME="AwardVoting"
APP_ENV=local
APP_KEY=
PAYSTACK_PUBLIC_KEY=
PAYSTACK_SECRET_KEY=
PAYSTACK_WEBHOOK_SECRET=
```

### Paystack Test Mode
- Use Paystack test keys for development
- Test card: 4123450131001381 / any future date / any CVV