# PHP Target Architecture

## Stack

- PHP 8.x
- MySQL/MariaDB
- PDO for database access
- Composer for dependencies
- PHPMailer or Symfony Mailer for email sending
- Vanilla JavaScript for small interactions
- Apache `.htaccess` routing for Namecheap shared hosting

## Folder Layout

```text
php-app/
  public/
    index.php
    assets/
  app/
    Controllers/
    Models/
    Services/
    Views/
  config/
  database/
    migrations/
    dumps/
  storage/
    uploads/
```

## Main Modules

- Admin authentication and roles
- Voter import and management
- Voter password setup links
- Password login and password reset
- Election setup
- Position/section setup
- Candidate/nominee setup with photos
- Ballot entry and review
- Vote submission
- Receipt checking
- Results reports
- Audit logs

## Proposed Core Tables

- `admin_users`
- `admin_roles`
- `voter_groups`
- `voters`
- `voter_password_tokens`
- `voter_login_logs`
- `elections`
- `election_eligible_groups`
- `positions`
- `candidates`
- `voter_participation`
- `vote_records`
- `election_action_logs`
- `audit_events`
- `school_branding`

## New Password Setup Flow

1. Admin imports or creates voters.
2. System sends each voter a one-time password setup link by email.
3. The raw token appears only in the email link.
4. The database stores only a hash of the token.
5. Voter opens the link and creates a password.
6. Password is stored with PHP `password_hash`.
7. Token is marked used.
8. Voter later logs in using email plus password.

## Security Rules

- Store password hashes only, never plain passwords.
- Store setup/reset token hashes only, never raw tokens.
- Use prepared statements everywhere.
- Use CSRF tokens for forms.
- Regenerate session IDs after login.
- Keep upload folders protected against executing PHP files.
- Use HTTPS on Namecheap.
- Keep admin and voter sessions separate.

## Migration Order

1. Export original database.
2. Reconstruct exact original schema from `models.py`, migrations, or database introspection.
3. Build MySQL schema.
4. Convert PostgreSQL data types to MySQL-compatible types.
5. Import voters, groups, elections, positions, candidates, and photos.
6. Import historical participation and vote records.
7. Import audit/history records.
8. Generate password setup tokens for voters who need passwords.
9. Test old election results against new PHP results.
10. Deploy to Namecheap and test email delivery.