# Election Management System — cPanel Deployment Guide

## Requirements (confirm in your cPanel)
- PHP 8.2+
- MySQL 8.0+
- Composer (via SSH or cPanel Terminal)
- mod_rewrite enabled
- extensions: pdo_mysql, mbstring, openssl, tokenizer, xml, ctype, json, bcmath, gd, zip

---

## Step 1: Upload Files

1. Log in to **cPanel → File Manager**
2. Navigate to your domain's **public_html** folder (or a subfolder like `public_html/election`)
3. Upload and extract **election-system.zip** there
4. Your directory should look like:
   ```
   public_html/
   ├── app/
   ├── bootstrap/
   ├── config/
   ├── database/
   ├── public/          ← this is the web root Laravel needs
   ├── resources/
   ├── routes/
   ├── storage/
   └── ...
   ```

---

## Step 2: Point the Domain to /public

**Option A: cPanel Subdomain/Addon Domain**
- When creating the domain, set **Document Root** to: `public_html/election/public`

**Option B: cPanel → Subdomains or .htaccess redirect**
- The root `.htaccess` is already configured to redirect to `/public`
- Alternatively use **cPanel → MultiPHP** to confirm PHP 8.2

---

## Step 3: Create MySQL Database

1. cPanel → **MySQL Databases**
2. Create a new database: e.g., `youruser_election`
3. Create a user and set a strong password
4. Assign the user to the database with **All Privileges**
5. Note the database name, username, and password

---

## Step 4: Configure .env

1. In File Manager, copy `.env.example` to `.env`
2. Edit `.env`:

```env
APP_NAME="Election Management System"
APP_ENV=production
APP_KEY=                        # will be generated in Step 5
APP_DEBUG=false
APP_URL=https://yourdomain.com  # your actual domain

DB_CONNECTION=mysql
DB_HOST=localhost               # or 127.0.0.1
DB_PORT=3306
DB_DATABASE=youruser_election   # your DB name
DB_USERNAME=youruser_dbuser     # your DB username
DB_PASSWORD=your_strong_password
```

---

## Step 5: Run Setup Commands (via SSH or cPanel Terminal)

```bash
# Navigate to your project directory
cd public_html/election

# Install PHP dependencies
composer install --optimize-autoloader --no-dev

# Generate the application key
php artisan key:generate

# Run database migrations + seed (creates default admin)
php artisan migrate --seed

# Create the storage symlink (so uploaded files are accessible)
php artisan storage:link

# Cache configuration for performance
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Set folder permissions
chmod -R 775 storage bootstrap/cache
```

---

## Step 6: First Login

Open your browser and go to:
```
https://yourdomain.com/admin
```

**Default credentials:**
| Field    | Value                |
|----------|----------------------|
| Email    | admin@election.local |
| Password | Admin@123456         |

> **IMPORTANT:** Change the password immediately after first login!
> Go to: Admin → your profile icon → Edit Profile

---

## Step 7: Set Up a Cron Job (for auto-closing elections)

1. cPanel → **Cron Jobs**
2. Add a new cron job — every hour:
   ```
   0 * * * * /usr/local/bin/php /home/yourusername/public_html/election/artisan schedule:run >> /dev/null 2>&1
   ```
   (Adjust the PHP path to match your server — usually `/usr/local/bin/php` or `/usr/bin/php8.2`)

---

## Step 8: Verify Installation

- [ ] Public manifesto page loads: `https://yourdomain.com/manifesto`
- [ ] Voter portal loads: `https://yourdomain.com/vote`
- [ ] Admin panel loads: `https://yourdomain.com/admin`
- [ ] Admin login works with new password
- [ ] File uploads work (create a test candidate with a photo)

---

## How to Use the System

### 1. Create an Election
Admin → Elections → New Election
- Set title, description
- Set manifesto period (when public can view candidates)
- Set voting period (when voters can cast votes)
- Set status to **Active**

### 2. Create Positions
Admin → Positions → New Position
- Assign to the election
- Name: President, Secretary, Treasurer, etc.
- Set sort order (1 = first on ballot)

### 3. Add Candidates
Admin → Candidates → New Candidate
- Select position
- Upload photo (JPG/PNG, will be cropped to square)
- Upload manifesto PDF (optional)
- Add biography and campaign message

### 4. Import Voters
Admin → Voters → Import Voters (Excel/CSV button)
- Use the provided **voter_import_template.csv**
- Columns: `full_name`, `telephone`, `unique_id`
- Unique ID must be unique per election
- Phone numbers are used for voter verification

### 5. Monitor in Real-Time
Admin → Live Dashboard (or navigate via Filament sidebar)
- Auto-refreshes every 30 seconds
- Shows votes by position and candidate

### 6. Generate Reports
Admin → Reports
- View, PDF, or Excel for:
  - Final results (with winners highlighted)
  - Voter turnout (who voted and when)
  - Audit log (all actions, IPs, timestamps)

### 7. Publish Results
Admin → Elections → Edit
- Toggle **Publish Results** when ready to make results public

---

## Security Features

- One vote per voter (enforced at DB level with UNIQUE constraint)
- Votes cannot be edited or deleted after submission
- Admin cannot vote on behalf of voters (voter session is separate)
- All actions are logged in the audit table
- Elections automatically close after voting period ends
- CSRF protection on all forms
- SQL injection protection via Eloquent ORM
- Sessions encrypted (AES-256-CBC)

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| 500 error after upload | Check `.env` is configured and `APP_KEY` is set |
| White page / blank | Set `APP_DEBUG=true` temporarily to see error |
| Images not loading | Run `php artisan storage:link` |
| Cannot log in to admin | Run `php artisan migrate --seed` to create admin user |
| Voters can't log in | Ensure telephone matches exactly (system normalizes digits only) |
| PDF not generating | Check `gd` and `dom` PHP extensions are enabled |
| Excel import fails | Ensure columns are exactly: `full_name`, `telephone`, `unique_id` |

---

## File Structure Summary

```
app/
  Models/         — Election, Position, Candidate, Voter, Vote, AuditLog, User
  Http/
    Controllers/  — VotingController, ManifestoController, ReportController
  Filament/
    Resources/    — Admin CRUD panels
    Widgets/      — Dashboard charts
    Pages/        — Live dashboard page
  Imports/        — VotersImport (Excel/CSV)
  Exports/        — ResultsExport, VoterTurnoutExport, AuditLogExport
  Console/        — AutoCloseElections command
database/
  migrations/     — All DB table definitions
  seeders/        — Creates default admin user
resources/views/
  manifesto/      — Public candidate/manifesto pages
  voting/         — Voter login, ballot, success, error pages
  dashboard/      — Live dashboard & reports
  reports/pdf/    — PDF templates (results, turnout, audit)
  filament/       — Filament custom page views
routes/
  web.php         — All public + admin routes
config/           — Laravel + Filament configuration
```