# Voting System Migration Notes

Date: 2026-05-20

## Goal

Move the current local voting system to a Namecheap Stellar Plus shared-hosting friendly stack, rewriting the app from Django/Python to PHP with MySQL/MariaDB.

The PHP version should preserve all existing data, including voters, groups, elections, positions, candidates, vote history, receipts, audit logs, and login/link history where available.

## Confirmed Decisions

- Hosting target: Namecheap Stellar Plus shared hosting.
- Backend target: PHP with MySQL/MariaDB.
- Frontend: HTML/CSS with light JavaScript where useful.
- Voter authentication should change from direct magic-link login to email setup links.
- Voters receive an email link, open it, create a password, then log in with their password afterward.
- Historical votes and election records should be migrated, not discarded.

## Current Workspace

- Target folder: `C:\Users\kasir\Desktop\Voting System`
- Preserved intake folder: `_intake`
- PHP rewrite folder: `php-app`
- Planning docs folder: `docs`

## What Has Been Copied

- Partial Django app found at `C:\Users\kasir\Desktop\mine\.codex_remote`
- Nominee/student assets found under `C:\Users\kasir\Desktop\STUDENTS`
- Nominee assets and spreadsheet from `C:\Users\kasir\Desktop\mine`
- Full server backup archive from `C:\Users\kasir\Desktop\BACKUP\mydjangoapp-backup.tar.gz`
- Extracted full Django app at `_intake\original-backup-20260520-0923\mydjangoapp`
- Live SQLite database copied to `php-app\database\dumps\original-db-20260520-0923.sqlite3`
- Uploaded media copied to `php-app\public\uploads`

## Important Finding

The full Django system is now present in the migration workspace.

Extraction produced Windows symlink warnings inside the Linux `venv` folder only. The application source, media, scripts, Docker files, and `db.sqlite3` extracted successfully.

## Database Finding

Updated from project findings:

- The actual `.env` in the original project uses `DATABASE_URL=sqlite:///db.sqlite3`.
- The original project does not set explicit `POSTGRES_*` values.
- The PostgreSQL values in `settings.py` are defaults only.
- No `.sql`, `.sql.gz`, `.dump`, or similar database export was found in the repository.
- `backup.sh` and `restore.sh` should be used from the original `mydjangoapp` project when that full folder is available.

Because the original `.env` points to SQLite, the first priority is now to copy/export `db.sqlite3` from the real original project root.

PostgreSQL should only be revisited if the Docker runtime is actually using the `db` service instead of the `.env` SQLite setting.

## Source Data Inventory

Extracted from `original-db-20260520-0923.sqlite3`:

- Admin users: 5
- Voter groups: 4
- Voters: 98
- Legacy login tokens: 566
- Magic-link request logs: 142
- Elections: 2
- Eligible group links: 4
- Positions/categories: 16
- Candidates/nominees: 53
- Voter participation records: 73
- Vote records: 217
- Election action logs: 22
- Audit events: 1,254
- School branding records: 1

The extracted table count report is at `php-app\database\dumps\original-table-counts-20260520-0923.tsv`.

## Migration Test Result

A local MySQL test database named `voting_system_migration_test` was created in XAMPP MySQL.

The PHP target schema was applied successfully, and `php-app\scripts\import_sqlite_to_mysql.php` imported the SQLite data successfully with matching core counts.

## PHP Feature Progress

Implemented and verified:

- Voter password setup request page.
- One-time password setup token generation.
- Local development setup link display.
- Password creation with PHP `password_hash`.
- Voter email/password login with `password_verify`.
- Login attempt logging.
- Voter logout.
- Basic voter dashboard from migrated MySQL data.

The original SQLite backup remains unchanged. Verification was performed against the local MySQL migration test database.

## Data We Need Next

To create the full backup and migration dump, we still need one of these:

- The full source folder from the local server, including `manage.py`, app modules, migrations, media, and `.env`.
- Or access to the live server filesystem.
- Or a copy of `db.sqlite3` from the original `mydjangoapp` root.
- Or a database export generated by `backup.sh`.

## Import Command Once Source Path Is Known

```powershell
cd "C:\Users\kasir\Desktop\Voting System"
.\scripts\import-original-system.ps1 -SourcePath "C:\path\to\mydjangoapp"
```

If the source folder contains a safe `backup.sh` and Git Bash is available:

```powershell
.\scripts\import-original-system.ps1 -SourcePath "C:\path\to\mydjangoapp" -RunBackupScript
```

## PostgreSQL Export Command If Needed Later

For PostgreSQL on this PC:

```powershell
$env:PGPASSWORD='REAL_PASSWORD'
& 'C:\Program Files\PostgreSQL\18\bin\pg_dump.exe' `
  -h 127.0.0.1 `
  -p 12700 `
  -U REAL_USER `
  -d REAL_DATABASE `
  -Fc `
  -f 'C:\Users\kasir\Desktop\Voting System\php-app\database\dumps\original-voting-system.dump'
```

For a plain SQL export:

```powershell
$env:PGPASSWORD='REAL_PASSWORD'
& 'C:\Program Files\PostgreSQL\18\bin\pg_dump.exe' `
  -h 127.0.0.1 `
  -p 12700 `
  -U REAL_USER `
  -d REAL_DATABASE `
  -f 'C:\Users\kasir\Desktop\Voting System\php-app\database\dumps\original-voting-system.sql'
```

## Migration Rule For Vote Privacy

The existing app appears to store voter participation separately from individual vote records. The PHP rewrite should preserve that behavior:

- `voter_participation` records that a voter has voted and stores receipt verification.
- `vote_records` stores election/position/candidate selections without storing the voter ID.

This keeps vote counting possible while reducing direct voter-to-choice linkage.