Automated Student Clearance and Certificate Issuance System
Final-year BSc Computer Science project: design and implementation of an automated student clearance system.
server/: Node.js + Express REST API, MySQL 8 (workflow engine, uploads, Paystack, PDFs, email)client/: React (Vite) frontend: student (mobile-first), staff review, admin, public verificationdocs/SPEC.md: the agreed specification (with amendments); docs/ui-design.md + docs/ui-mockups/: the agreed UI
Prerequisites
- Node.js 18+ (developed on Node 24)
- MySQL 8 (developed on 8.4) running locally
First-time setup
cp .env.example .env # set DB_PASSWORD, JWT_SECRET, Paystack test keys; EmailJS keys if using email
cd server
npm install
npm run db:migrate # creates clearance_db and all tables
npm run db:seed # stages, required documents, test staff accounts (passwords printed once)
npm run import:students -- ../data/class-list.csv # import the class list
npm run db:seed # again, to create officers for any new departments
cd ../client
npm install
Running
From the clearance-system folder, one command starts both parts:
npm run dev # API on :4000 and the app on :5173; Ctrl+C stops both
Open http://localhost:5173. (Or run them separately: npm run dev inside server and inside client.)
| Who | Where | How |
|---|
| Student | /student (login at /student/login) | Reg number, then tap your name, then password. New students use /student/signup. |
| Staff | /staff (login at /staff/login) | Email + password (forced change on first login) |
| Admin | /admin (login at /staff/login) | [email protected] (see staff-credentials.local.txt) |
| Registry | /staff/registry (login at /staff/login) | [email protected] (see staff-credentials.local.txt) |
| Anyone | /verify | Certificate verification, no login |
The student portal and the staff portal keep separate logins, so you can be logged in to both in the same
browser (for example a student tab and a reviewer tab side by side) without one replacing the other.
Demo data (for presentations)
cd server && npm run demo
Resets two demo students to match the mockups. Password for all demo accounts: Demo@12345.
2022/248400 (ALIOZOR): departmental + faculty approved, library card sent back as blurry, N3,000 library fee due2022/242722 (ALOGO): departmental receipts waiting for review; the 300 level receipt is a duplicate[email protected]: departmental officer, Computer Science
Tests
cd server && npm test # 107 tests: rules, auth, workflow end to end, uploads, payments, PDFs, notifications, admin
Tests use the local database and clean up after themselves. They never send real email and never contact Paystack.
Payments (Paystack test mode)
Use Paystack's test card on the checkout page: 4084 0840 8408 4081, any future expiry, CVV 408, PIN 0000, OTP 123456.
Payments are confirmed by the server calling Paystack's verify API when the student returns. The webhook
(/api/payments/webhook/paystack) also works once the API is reachable from the internet (deployment or a tunnel).
Email (optional)
Set EMAIL_ENABLED=true and the EMAILJS_* values in .env (free tier: 200 emails/month).
Every in-app notification is then also emailed to the person it concerns.
Password reset links ("Forgot password?" on both login pages) are sent the same way. Addresses ending in
.test (the seeded staff accounts) cannot receive email; with email off, or for those addresses, the
reset link is printed in the server console instead.
Deploying (Vercel + Aiven MySQL)
The website and the API run on Vercel (one project: vercel.json, API entry api/index.js);
the database is a free Aiven MySQL service. Uploaded files and generated PDFs are kept in the
database (STORAGE_DRIVER=db), because Vercel has no permanent disk. Background OCR is off on
Vercel (OCR_ENABLED=false); reviewers still confirm names with the tick box.
- Aiven: create a free MySQL service; note host, port, user, password, database (
defaultdb)
and download the CA certificate (ca.pem, keep it in clearance-system/, it is git-ignored).
- Copy local data to Aiven: create
clearance-system/.env.hosted with TARGET_DB_HOST,
TARGET_DB_PORT, TARGET_DB_USER, TARGET_DB_PASSWORD, TARGET_DB_NAME,
TARGET_DB_SSL_CA_FILE=ca.pem, then run node server/scripts/copyToHosted.js.
- Vercel: import the GitHub repo (no settings to change;
vercel.json has them) and add these
Environment Variables: DB_HOST DB_PORT DB_USER DB_PASSWORD DB_NAME DB_SSL_CA (contents of
ca.pem) DB_POOL_SIZE=3 STORAGE_DRIVER=db OCR_ENABLED=false UPLOAD_MAX_MB=4 JWT_SECRET JWT_EXPIRES_IN CURRENT_SESSION APP_BASE_URL (the Vercel address) PAYSTACK_SECRET_KEY PAYSTACK_PUBLIC_KEY EMAIL_ENABLED EMAIL_PROVIDER EMAILJS_*.
- Paystack dashboard: set the webhook URL to
<APP_BASE_URL>/api/payments/webhook/paystack.
