🎓 CCA Offer Student Onboarding

A production-oriented student registration, payment, and admin operations system for CCA special-offer bootcamp onboarding.

✨ Overview

CCA Offer Student Onboarding is a full-stack Next.js application built to handle the complete registration lifecycle for special-offer bootcamp intakes:

🧭 guided public onboarding flow
🧾 structured student detail capture and validation
💳 secure online payment initiation through PayHere
🏦 manual bank-transfer slip upload and verification workflows
🗂️ admin dashboard for records, exports, editing, and payment review
🗃️ Neon Postgres-backed student persistence
☁️ Vercel Blob-backed private payment-slip storage and downloadable receipt generation
📲 optional SMS confirmation hooks for operational follow-up

This repository is maintained by Codezela Technologies and the source repository lives at:

GitHub: https://github.com/codezelat/cca-offer-student-onboarding

🚀 Key Highlights

👨‍🎓 Student-facing capabilities

Select one or two bootcamp programs in a single onboarding journey.
Pass through a multi-step guided registration process.
Validate core student details including:
- Sri Lankan NIC
- email address
- district
- phone formats
- registration ID pattern
Continue through multiple payment paths:
- PayHere online card payment
- bank transfer with payment-slip upload
View success states and registration confirmations after completion.
Generate and access downloadable receipt views through signed receipt links or the admin area.

🧑‍💼 Admin capabilities

Secure admin login backed by encrypted session cookies.
Paginated student dashboard with search, filters, and manual record creation.
Individual student record view and edit flows.
Manual admin-side grouped registration creation for one or two bootcamps.
Optional bank-slip attachment during manual admin record creation.
Student deletion support through admin API routes.
Export student data to XLSX.
Access uploaded payment slips through secured file-serving routes.

⚙️ Operational capabilities

Prisma-backed student persistence.
Neon/Postgres runtime by default, with MySQL schema assets still present as alternate schema assets.
Private Vercel Blob storage for payment slips.
Optional SMS notifications when payment or registration workflows complete.
Deadline-driven registration control using environment-configurable timing.

🧠 Product Flow

The platform is built around a staged registration journey. Registration data is first validated and staged in an encrypted cookie session, then committed into the database once a payment completion path is chosen.

flowchart LR
    A["Landing Page"] --> B["Select 1-2 Bootcamps"]
    B --> C["Eligibility Check"]
    C --> D["Registration Form"]
    D --> E["Validate + Stage In Session"]
    E --> F["Payment Options"]
    F --> G["PayHere Online Payment"]
    F --> H["Bank Transfer Slip Upload"]
    F --> I["Study Now / Pay Later Completion Route"]
    G --> J["Payment Notify + Success View"]
    H --> K["Slip Saved + Student Persisted"]
    I --> L["Registration Success"]
    J --> M["Admin Dashboard / Export / Receipt / Slip Access"]
    K --> M
    L --> M

🪜 Registration sequence

Student lands on the public home page.
Student selects one or two bootcamps.
Eligibility step determines whether the user can continue.
Registration details are submitted to /api/register.
Valid data is stored in the encrypted session cookie.
Student chooses a payment path.
Final records are written to the database when payment flow completes.
Admins can review, export, edit, or inspect uploaded artifacts afterward.

🧾 Data model behavior worth knowing

A single student journey can create multiple database rows when two bootcamps are selected.
Registration IDs may be suffixed internally with -1, -2, and so on for multi-bootcamp persistence.
Duplicate checks are scoped per bootcamp using normalized:
- NIC
- email
- WhatsApp number

🛠️ Tech Stack

Layer	Technology
Frontend	Next.js 16 App Router, React 19
Language	TypeScript
Styling	Tailwind CSS v4
Database ORM	Prisma 7
Default Runtime Database	Neon Postgres
Additional Database Schema Assets	MySQL Prisma schema and generated client output
Testing	Vitest
Validation	Zod
Auth/session storage	Encrypted JWT cookie via `jose`
File generation	`pdf-lib`, custom XLSX generation, `yazl`
File persistence	Vercel Blob private storage
Payments	PayHere
Messaging	External SMS gateway integration

🗺️ Application Routes

🌐 Public pages

Route	Purpose
`/`	Landing page and primary campaign entry point
`/select-bootcamp`	Bootcamp selection flow
`/check-eligibility`	Eligibility gate before registration
`/register`	Student registration form
`/payment/options`	Payment method selection
`/payment/payhere`	PayHere launch screen
`/payment/payhere-success`	Payment completion / processing state
`/payment/upload-slip`	Bank-transfer slip upload
`/payment/slip-success`	Slip submission success view
`/registration-success`	Success page for non-card completion flow
`/payment/receipt/[id]`	Receipt display page with signed-link or admin access
`/offer-ended`	Deadline-closed state

🧑‍💼 Admin pages

Route	Purpose
`/cca-admin-login`	Admin login
`/cca-admin-area/dashboard`	Student dashboard
`/cca-admin-area/student/new`	Manual admin record creation
`/cca-admin-area/student/[id]`	Student detail view
`/cca-admin-area/student/[id]/edit`	Student edit screen

📁 File-serving routes

Route	Purpose
`/files/slips/[studentId]`	Download or view uploaded slip file for a student
`/payment/receipt/[id]/download`	Receipt download route

🔌 API Surface

📝 Registration and payment APIs

Endpoint	Method	Purpose
`/api/register`	`POST`	Validate and stage registration data in session
`/api/payment/blob/upload`	`POST`	Authorize direct private slip uploads to Vercel Blob
`/api/payment/payhere/start`	`POST`	Build PayHere payment payload and redirect to payment launcher
`/api/payment/notify`	`POST`	Verify PayHere callback signature and mark payment complete
`/api/payment/store-slip`	`POST`	Validate and store uploaded payment slip
`/api/payment/agree`	`POST`	Complete the non-card registration path
`/api/payment/session/clear`	`POST`	Clear staged payment session data

🧑‍💼 Admin APIs

Endpoint	Method	Purpose
`/api/admin/login`	`POST`	Authenticate admin session
`/api/admin/logout`	`POST`	Clear admin session
`/api/admin/export`	`GET`	Export filtered student records to XLSX
`/api/admin/student`	`POST`	Create a manual admin student registration
`/api/admin/student/slip-upload`	`POST`	Authorize optional admin-side slip upload during manual record creation
`/api/admin/student/[id]`	`GET`	Retrieve student details
`/api/admin/student/[id]`	`PUT`	Update student data
`/api/admin/student/[id]`	`PATCH`	Approve a pending bank-slip registration group
`/api/admin/student/[id]`	`DELETE`	Delete a student record

🏗️ Project Structure

.
├── AGENTS.md
├── README.md
├── app/
│   ├── api/
│   ├── cca-admin-area/
│   ├── cca-admin-login/
│   ├── check-eligibility/
│   ├── files/
│   ├── payment/
│   ├── register/
│   ├── registration-success/
│   └── select-bootcamp/
├── components/
│   ├── admin/
│   ├── forms/
│   └── ui/
├── generated/
│   ├── mysql/
│   └── postgres/
├── lib/
│   ├── content/
│   ├── auth.ts
│   ├── config.ts
│   ├── db.ts
│   ├── env.ts
│   ├── flow.ts
│   ├── ids.ts
│   ├── payhere.ts
│   ├── session.ts
│   ├── sms.ts
│   ├── storage.ts
│   ├── student-service.ts
│   ├── types.ts
│   ├── validation.ts
│   └── xlsx.ts
├── prisma/
│   ├── mysql/
│   └── postgres/
├── public/
│   └── images/
└── tests/

📌 Important source files

lib/config.ts contains business constants, fee values, bootcamp names, support details, and deadline accessors.
lib/env.ts defines environment-variable handling and required runtime configuration.
lib/validation.ts is the core validation source of truth for registration input.
lib/session.ts controls encrypted cookie session behavior.
lib/student-service.ts contains persistence, payment-completion, duplication, and dashboard logic.
lib/storage.ts handles Blob-backed payment-slip validation, reads, and deletes.
prisma/postgres/schema.prisma defines the default runtime data model.
.env.example shows the required local and deployed configuration variables.

⚙️ Environment Configuration

The app no longer uses code-level fallback credentials or fallback session secrets. Operational settings should be set explicitly in local development and in each deployed environment.

🔑 Supported environment variables

Variable	Purpose	Local behavior / default
`APP_URL`	Base URL used for generated absolute links and callbacks	Defaults to `http://localhost:3000`
`ADMIN_USERNAME`	Admin login username	Required
`ADMIN_PASSWORD`	Admin login password	Required
`COUNTDOWN_DEADLINE`	Offer expiry and countdown cutoff	Required
`SESSION_SECRET`	Secret used for encrypted JWT session cookies	Required
`DATABASE_URL`	Runtime Neon/Postgres connection string used by the Prisma Neon adapter	No production-safe default
`DIRECT_URL`	Direct Postgres connection string used by Prisma CLI commands	Falls back to `DATABASE_URL` in `prisma.config.ts`
`BLOB_READ_WRITE_TOKEN`	Vercel Blob token for private uploads and reads	Required for slip uploads and admin slip access
`PAYHERE_MERCHANT_ID`	PayHere merchant ID	Required for real online payments
`PAYHERE_MERCHANT_SECRET`	PayHere merchant secret	Required for hash generation and callback verification
`PAYHERE_SANDBOX`	Toggle PayHere sandbox behavior	Defaults to `true`
`SMS_USERNAME`	SMS gateway username	Optional
`SMS_PASSWORD`	SMS gateway password	Optional
`SMS_SOURCE`	Sender/source identifier for SMS	Optional
`SMS_API_URL`	SMS provider endpoint	Optional

🔐 Sensitive configuration note

These values must be supplied explicitly:

ADMIN_USERNAME
ADMIN_PASSWORD
SESSION_SECRET
COUNTDOWN_DEADLINE

If any of them are missing, the app should fail fast instead of silently booting with insecure defaults.

💾 Database And Storage

🗄️ Default runtime database

The live application code uses the Postgres Prisma client generated under:

generated/postgres/client

The runtime connection is handled by the Prisma Neon adapter in lib/db.ts and expects a Neon/Postgres DATABASE_URL.

The Prisma CLI uses:

DIRECT_URL when present
otherwise DATABASE_URL

🧬 Student model fields

The primary persisted entity is Student, which includes:

registration identifiers
student identity fields
selected bootcamp
normalized duplicate-detection fields
payment method and status
payment slip blob pathname
PayHere order ID
amounts and timestamps

📁 File storage

Uploaded payment slips are stored in:

private Vercel Blob storage

Operationally, this means:

uploads do not rely on the local filesystem
admin slip access is mediated through the application route at /files/slips/[studentId]
BLOB_READ_WRITE_TOKEN must be configured in both local development and Vercel

🧠 Database notes

Neon/Postgres is the active runtime path in the current codebase.
MySQL Prisma schema assets exist under prisma/mysql, but the main application imports the Postgres-generated client.
The Prisma CLI path is configured in prisma.config.ts.

▶️ Getting Started

1. ✅ Prerequisites

Node.js 20 or newer
npm

2. 📥 Install dependencies

npm install

3. 🔄 Generate Prisma client

npm run prisma:generate

4. 🗃️ Prepare the database

Copy the example environment file and fill in your real values:

cp .env.example .env

At minimum for local app flows you need:

DATABASE_URL
DIRECT_URL
BLOB_READ_WRITE_TOKEN

The app is designed for Neon Postgres in both local development and Vercel deployment.

Once your database credentials are set, sync the schema:

npm run prisma:push

If you are using a migration-based local workflow:

npm run prisma:migrate

5. 🚀 Start the development server

npm run dev

Open:

http://localhost:3000

6. 👩‍💼 Access the admin panel

Use:

http://localhost:3000/cca-admin-login

Use the ADMIN_USERNAME and ADMIN_PASSWORD values from your local .env.

🧪 Testing

Run the full test suite:

npm test

Run tests in watch mode:

npm run test:watch

🔍 Covered areas

copy parity checks
registration validation
Sri Lankan NIC validation
registration ID generation
PayHere hash generation
XLSX workbook generation

🧾 Useful test files

tests/copy-parity.test.ts
tests/validation.test.ts
tests/nic.test.ts
tests/ids.test.ts
tests/payhere.test.ts
tests/xlsx.test.ts

📦 Build And Deployment Notes

Create a production build:

npm run build

Run the production server locally:

npm run start

🚢 Deployment considerations

Set APP_URL to the actual public base URL.
Set a strong SESSION_SECRET.
Set explicit admin credentials.
Configure DATABASE_URL and DIRECT_URL for Neon Postgres.
Configure BLOB_READ_WRITE_TOKEN for Vercel Blob.
Configure real PayHere merchant credentials for card payments.
Keep the upload flow on private Blob storage; it is already designed to avoid Vercel’s server body-size bottleneck by using direct client uploads.

📤 Export behavior

The admin export endpoint returns an .xlsx workbook containing registration and payment fields, including hyperlinks to uploaded slip files when present.

🔐 Security And Operational Notes

🔒 Sessions

Admin and staged-registration state are stored in encrypted JWT cookies.
Cookies are marked httpOnly.
Secure cookies are enabled automatically in production.

💳 Payments

Card details are handled by PayHere, not stored directly by this application.
PayHere notifications are verified with MD5-based signature logic in lib/payhere.ts.
Payment-completion code paths should be treated as security-sensitive.

📎 File uploads

The payment-slip upload flow accepts these file extensions:

jpg
jpeg
png
pdf
docx
doc

Maximum allowed file size:

10 MB

Storage backend:

Private Vercel Blob

📲 SMS behavior

SMS delivery is optional. If SMS credentials are not configured, the app safely skips outbound delivery rather than failing the registration flow.

⏳ Deadline gating

Registration availability is controlled by COUNTDOWN_DEADLINE. Once the deadline passes, the onboarding flow redirects to the offer-ended state.

🏢 Ownership And Branding

This project is built and maintained by Codezela Technologies.

Company website: https://codezela.com
Repository: https://github.com/codezelat/cca-offer-student-onboarding

For branding, ownership, usage authorization, licensing, or implementation inquiries, use the official company website as the primary contact point.

📄 License

This repository is proprietary software owned by Codezela Technologies.

License file: LICENSE
Public reuse, redistribution, sublicensing, or commercial exploitation is not permitted without prior written authorization from Codezela Technologies.

Name		Name	Last commit message	Last commit date
Latest commit History 54 Commits
app		app
components		components
lib		lib
prisma		prisma
public/images		public/images
storage/payment_slips		storage/payment_slips
tests		tests
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
prisma.config.ts		prisma.config.ts
prisma.mysql.config.ts		prisma.mysql.config.ts
proxy.ts		proxy.ts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation