🎓 Codezela Career Accelerator (CCA) - Student Onboarding Portal

A comprehensive, enterprise-grade student registration and management system for Career Accelerator Programs

Features • Installation • Configuration • Usage • Admin Panel • API • Support

📋 Table of Contents

Overview
Features
Tech Stack
System Requirements
Installation
Configuration
Usage
Admin Panel
Database Schema
File Structure
Security
API Documentation
Best Practices
Deployment
Troubleshooting
Contributing
License
Support

🌟 Overview

The Codezela Career Accelerator (CCA) Student Onboarding Portal is a full-featured, production-ready web application designed to streamline the registration process for career development programs. Built with modern web technologies and following industry best practices, this system provides a seamless experience for both students and administrators.

Key Highlights

🎯 DB-Driven Program Catalog - Program codes, activation, intake windows, and pricing managed from admin
🌍 Multi-country Support - Sri Lanka districts + 195 countries
📁 Cloud Storage - Cloudflare R2 integration for secure document storage
🔒 Enterprise Security - reCAPTCHA v3, CSRF protection, XSS prevention
📊 Advanced Admin Dashboard - Real-time statistics, filtering, Excel export
💰 Payment Ledger - Multi-payment history with date, method, reference, void trail, and totals sync
🎨 Modern UI/UX - Responsive design, animations, dark/light themes
♿ Accessibility - WCAG 2.1 compliant, keyboard navigation, ARIA labels
📱 Mobile-First - Fully responsive across all devices

Recent Platform Updates (February 19, 2026)

✅ Payment ledger introduced with multi-payment rows and backward-compatible legacy backfill
✅ Program management moved from static config to database + admin UI
✅ Intake window-based registration opening/closing added
✅ Soft delete + restore for registrations and admin users
✅ Last-admin safety checks added to prevent lockout
✅ Admin activity timeline and CSV audit export implemented

✨ Features

🎓 Student Features

Registration System

Smart Program Selection - Real-time program validation with active/inactive status
Multi-document Upload - Academic qualifications, ID documents, passport, photos
Progress Tracking - Visual progress indicators during upload and submission
Duplicate Prevention - Automatic detection of existing registrations
Form Validation - Client-side and server-side validation with helpful error messages
Auto-fill Support - Browser autofill compatibility for faster form completion

Document Management

Multiple File Types - Support for PDF, JPG, PNG, HEIC, and more
File Size Validation - 10MB per file limit with user-friendly error messages
Secure Upload - Direct upload to Cloudflare R2 with encryption
Preview Support - View uploaded documents before submission

User Experience

3D Hero Section - Interactive Three.js animation on landing page
Animated Backgrounds - Liquid gradient blob animations
Glassmorphism UI - Modern frosted glass design elements
Real-time Feedback - Instant validation and status updates
Multi-step Forms - Organized sections with clear navigation
Helpful Tooltips - Contextual help throughout the form

👨‍💼 Admin Features

Dashboard

Real-time Statistics
- Total registrations count
- General rate registrations
- Special offer registrations
- Most registered program
Advanced Filtering - Search by name, email, phone, program
Pagination - Efficient data loading for large datasets
Export to Excel - One-click export of filtered results

Registration Management

Detailed View - Complete student information with all documents
Edit Capabilities - Update student information and program assignments
Payment Ledger Management
- Add unlimited payment rows per registration
- Edit/void payment rows with reason tracking
- Auto-sync of current_paid_amount from active ledger rows
Recovery & Safety
- Soft delete / restore registrations
- Permanent delete only from trash scope
- Last-admin deactivation/deletion protection

Admin Operations

Program Management UI - Activate/deactivate programs, maintain intake windows, and manage pricing
Admin Account Management - Create/deactivate/restore admin users with safeguards
Activity Timeline - Filterable admin audit log with detail view and CSV export

Document Viewer

Unified Viewer - View all student documents in one modal
Navigation Controls - Previous/Next buttons and keyboard shortcuts
Image Zoom & Pan - Zoom in/out with mouse wheel, drag to pan
PDF Support - Embedded PDF viewer with controls
Download Options - Direct download and open in new tab
Category Badges - Personal, Payment, Academic, Identity labels

User Management

Role-based Access - Admin roles with Spatie Permissions
Profile Management - Update admin profiles and passwords
Secure Authentication - Laravel Breeze with admin guard
Session Management - Remember me, timeout controls

🔒 Security Features

Protection Layers

Google reCAPTCHA v3 - Invisible bot protection on registration
CSRF Protection - Laravel's built-in CSRF tokens on all forms
XSS Prevention - Input sanitization and output escaping
SQL Injection Prevention - Eloquent ORM and prepared statements
File Upload Security - MIME type validation, size limits, virus scanning ready
Rate Limiting - Prevent brute force attacks
Security Headers - X-Frame-Options, X-Content-Type-Options, XSS-Protection

Data Privacy

Encrypted Storage - All files stored with encryption on Cloudflare R2
Secure URLs - Pre-signed URLs with expiration for document access
HTTPS Enforcement - Force HTTPS in production
No Index for Admin - Admin pages excluded from search engines
Audit Logging Active - Admin actions are logged to timeline with request context and before/after snapshots

🛠 Tech Stack

Backend

Laravel 12.x - PHP framework for web artisans
PHP 8.2+ - Modern PHP with type safety and performance
MySQL 8.0+ - Relational database (also supports PostgreSQL, SQLite)
Laravel Breeze - Authentication scaffolding
Spatie Laravel Permission - Role and permission management
Guzzle HTTP - API client for external services

Frontend

Blade Templates - Laravel's templating engine
Tailwind CSS 3.x - Utility-first CSS framework
Alpine.js 3.x - Lightweight JavaScript framework
Vite - Next-generation frontend tooling
Three.js - 3D graphics and animations
Axios - Promise-based HTTP client

Cloud Services

Cloudflare R2 - S3-compatible object storage
Google reCAPTCHA v3 - Bot protection
Google Analytics - Web analytics (production only)

Development Tools

Laravel Pint - PHP code style fixer
Laravel Pail - Real-time log viewer
Laravel Sail - Docker development environment
Composer - PHP dependency manager
NPM - JavaScript package manager

💻 System Requirements

Minimum Requirements

PHP: 8.2 or higher
Database: MySQL 8.0+ / PostgreSQL 13+ / SQLite 3.35+
Web Server: Apache 2.4+ / Nginx 1.18+
Node.js: 18.x or higher
NPM: 9.x or higher
Composer: 2.5+

Recommended Server Specifications

RAM: 2GB minimum, 4GB recommended
Storage: 10GB minimum (+ space for uploaded documents)
CPU: 2 cores minimum, 4 cores recommended
SSL Certificate: Required for production

PHP Extensions Required

- BCMath
- Ctype
- Fileinfo
- JSON
- Mbstring
- OpenSSL
- PDO
- Tokenizer
- XML
- GD or Imagick

🚀 Installation

Quick Start

# Clone the repository
git clone https://github.com/yourusername/cca-student-onboarding.git
cd cca-student-onboarding

# Install dependencies and setup
composer setup

# Start development servers
composer dev

Detailed Installation

1. Clone Repository

git clone https://github.com/yourusername/cca-student-onboarding.git
cd cca-student-onboarding

2. Install PHP Dependencies

composer install

3. Install Node Dependencies

npm install

4. Environment Configuration

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

5. Configure Environment Variables

Edit .env file with your settings:

# Application
APP_NAME=CCA
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Cloudflare R2 Storage
FILESYSTEM_DISK=r2
AWS_ACCESS_KEY_ID=your_r2_access_key
AWS_SECRET_ACCESS_KEY=your_r2_secret_key
AWS_DEFAULT_REGION=auto
AWS_BUCKET=your_bucket_name
AWS_ENDPOINT=https://your_account_id.r2.cloudflarestorage.com
AWS_USE_PATH_STYLE_ENDPOINT=false
AWS_URL=https://your_public_url.com

# Google reCAPTCHA v3
RECAPTCHA_SITE_KEY=your_site_key
RECAPTCHA_SECRET_KEY=your_secret_key
RECAPTCHA_MINIMUM_SCORE=0.5

# Mail Configuration (Optional)
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

6. Database Setup

# Run migrations
php artisan migrate

# Seed roles, admin user, and program catalog
php artisan db:seed

7. Storage Setup

# Create storage link (if using local storage)
php artisan storage:link

8. Build Assets

# For development
npm run dev

# For production
npm run build

9. Set Permissions

# Linux/Mac
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

# Or for development
chmod -R 777 storage bootstrap/cache

10. Start Application

# Development server
php artisan serve

# With queue worker
php artisan serve & php artisan queue:work

# Or use composer script
composer dev

⚙️ Configuration

Programs Configuration

Program catalog is now database-driven.

Manage programs at Admin → Program Management (/admin/programs)
Manage intake windows per program (opens_at, closes_at, is_active)
Manage pricing via base_price and optional intake price_override
Student registration is open only when both conditions are true:
- program is active
- at least one active intake window is open for current time

config/programs.php now contains only geographic lists (countries, sri_lanka_districts), not program catalog entries.

Cloudflare R2 Setup

Create R2 Bucket:
- Login to Cloudflare dashboard
- Navigate to R2 → Create bucket
- Note your Account ID and bucket name
Generate API Credentials:
- R2 → Manage R2 API Tokens
- Create API token with read/write permissions
- Copy Access Key ID and Secret Access Key
Configure Public Access (Optional):
- Enable custom domain for public access
- Configure CORS if needed

Update .env:

AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_BUCKET=your_bucket
AWS_ENDPOINT=https://account_id.r2.cloudflarestorage.com
AWS_URL=https://your_public_url.com

Google reCAPTCHA Setup

Register Site:
- Visit Google reCAPTCHA
- Register a new site with reCAPTCHA v3
- Add your domain
Get Keys:
- Copy Site Key and Secret Key

Configure .env:

RECAPTCHA_SITE_KEY=your_site_key
RECAPTCHA_SECRET_KEY=your_secret_key
RECAPTCHA_MINIMUM_SCORE=0.5

Admin User Creation

Default Admin Credentials:

Email: admin@cca.it
Password: password

Create Additional Admins:

php artisan tinker

# Then run:
$user = User::create([
    'name' => 'Admin Name',
    'email' => 'admin@example.com',
    'password' => bcrypt('secure_password'),
]);
$user->assignRole('admin');

Email Configuration

For sending notifications (optional):

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="CCA Portal"

📖 Usage

For Students

1. Access Registration Form

Navigate to https://your-domain.com/cca-register

2. Complete Form Sections

Program Information:

Enter your Program ID (e.g., CCA-PM25)
System validates and displays program details
Red warning appears if program is full

Personal Information:

Full name, date of birth
Gender selection
NIC or Passport number (at least one required)

Contact Information:

Permanent address
Country and district (Sri Lanka specific)
Email address
Phone number (with validation)
WhatsApp number

Guardian Information:

Guardian's name
Occupation
Contact number

Academic Qualifications:

Academic qualification level
Upload documents (PDF/Images, max 10MB each)

Identity Documents:

Upload NIC or Passport documents
Multiple files supported

Photo & Payment:

Upload passport-sized photo
Upload payment slip
Agree to terms and conditions

3. Submit Registration

Click "Submit Registration" button
Real-time progress indicator shows upload status
Success confirmation with registration ID
Automatic redirect to confirmation page

For Administrators

1. Login

Navigate to https://your-domain.com/admin/login

Default Credentials:

Email: admin@cca.it
Password: password

2. Dashboard Overview

View registration statistics
Filter by program, search students
Export data to Excel
Access individual registrations

3. View Registration Details

Click "View" button on any registration
See complete student information
View all uploaded documents
Check payment ledger summary and current paid total

4. Document Viewing

Click "View All" button in Documents section
Navigate through all documents with arrow keys
Zoom images with mouse wheel
Download or open in new tab

5. Edit Registration

Click "Edit" button on registration detail page
Update program assignment
Modify contact information
Save changes

6. Manage Payments

Open registration payment ledger
Add payment rows with date, method, amount, and receipt reference
Edit existing rows and void incorrect rows with reason
System auto-syncs current_paid_amount from active rows

7. Delete / Restore Registration

Click "Delete" button
Registration moves to trash scope (soft delete)
Restore from trash when needed
Permanent purge is available from trash scope only

8. Manage Programs / Intakes

Use Programs to activate/deactivate program catalog items
Add/edit intake windows and active windows
Set base price and optional intake price override

9. Manage Activity Timeline

Use Activity to review admin action history
Filter by date, actor, action, status, subject type, and search
Export filtered audit entries to CSV

10. Manage Profile

Click profile dropdown in navigation
Select "Profile Settings"
Update name, email, password
Logout securely

🎛 Admin Panel

Dashboard Features

Statistics Cards

Total Registrations - Overall count with blue gradient
General Rate Registrations - Count of general rate students (green)
Special Offer Registrations - Count of special offer students (purple)
Most Registered Program - Program with highest registrations (orange)

Filtering & Search

Search Bar - Search by name, email, phone, or NIC
Program Filter - Filter by specific program
Clear Filters - Reset all filters
Export Button - Export filtered results to Excel

Registration Table

Registration ID - Auto-generated unique ID
Student Name - Full name with email
Program - Program code with badge
Contact - Phone and WhatsApp
Submitted Date - Registration timestamp
Actions - View, Edit, Delete buttons

Payment Management

Payment Ledger

Multiple Payments - Unlimited installments per registration
Ledger Fields - Payment no, date, amount, method, receipt reference, note
Void Trail - Keep history with void_reason and voided_at
Totals Sync - current_paid_amount auto-calculated from active payment rows

Backward Compatibility

Existing registrations continue to work
Legacy current_paid_amount can be backfilled as Payment #1 (payment_method=legacy)

Document Management

Document Viewer Features

Unified Interface - All documents in one modal
Navigation - Previous/Next buttons, arrow keys, document counter
Image Controls - Zoom in/out, pan, reset zoom
PDF Support - Embedded viewer with toolbar
Download - Direct download button
Open in Tab - View in separate browser tab
Error Handling - Graceful fallback for unsupported formats

Supported File Types

Images: JPG, JPEG, PNG, GIF, WebP, HEIC, SVG, BMP
Documents: PDF
Error Display - User-friendly message for unsupported files

🗄 Database Schema

`users` Table

- id: bigint (PK)
- name: varchar(255)
- email: varchar(255) UNIQUE
- email_verified_at: timestamp (nullable)
- password: varchar(255)
- remember_token: varchar(100) (nullable)
- deleted_at: timestamp (nullable, soft delete)
- created_at: timestamp
- updated_at: timestamp

`cca_registrations` Table

- id: bigint (PK, auto-increment)
- register_id: varchar(20) UNIQUE (auto-generated)
- program_id: varchar(20)
- program_name: varchar(255)
- program_year: varchar(10)
- program_duration: varchar(50)
- full_name: varchar(255)
- date_of_birth: date
- gender: varchar(20)
- nic_number: varchar(20) (nullable)
- passport_number: varchar(50) (nullable)
- permanent_address: text
- country: varchar(100)
- province: varchar(100) (nullable)
- district: varchar(100) (nullable)
- email: varchar(255)
- phone_number: varchar(20)
- whatsapp_number: varchar(20)
- guardian_name: varchar(255)
- guardian_occupation: varchar(255)
- guardian_contact: varchar(20)
- academic_qualification: varchar(255)
- academic_qualification_documents: json (R2 URLs array)
- nic_documents: json (R2 URLs array)
- passport_documents: json (R2 URLs array)
- passport_photo: json (R2 URL object)
- payment_slip: json (R2 URL object)
- tags: json (nullable, payment tags array)
- current_paid_amount: decimal(10,2) (nullable)
- terms_accepted: boolean
- deleted_at: timestamp (nullable, soft delete)
- created_at: timestamp
- updated_at: timestamp

Indexes:
- program_id
- email
- nic_number
- passport_number
- register_id (unique)

Additional Tables (2026-02-19 Updates)

registration_payments
- id, cca_registration_id, payment_no, payment_date, amount
- payment_method, receipt_reference, note
- status (active|void), void_reason, voided_at
- created_by, updated_by, created_at, updated_at

programs
- id, code (unique), name, year_label, duration_label
- base_price, currency, is_active, display_order
- created_by, updated_by, created_at, updated_at

program_intake_windows
- id, program_id, window_name
- opens_at, closes_at, price_override
- is_active, created_by, updated_by, created_at, updated_at

admin_activity_logs
- actor_user_id, actor snapshots, category, action, status
- subject_type, subject_id, subject_label
- request metadata (route/method/ip/user-agent/request_id)
- before_data, after_data, meta

Data Migration Notes (Backward Compatibility)

Legacy current_paid_amount can be backfilled to registration_payments as Payment #1.
Program catalog can be seeded via ProgramSeeder and safely merged with legacy registration program IDs.

`roles` & `permissions` Tables

Managed by Spatie Laravel Permission package:

roles: id, name, guard_name, created_at, updated_at
permissions: id, name, guard_name, created_at, updated_at
model_has_roles: Pivot table
role_has_permissions: Pivot table

`jobs` Table

- id: bigint (PK)
- queue: varchar(255)
- payload: longtext
- attempts: tinyint
- reserved_at: int (nullable)
- available_at: int
- created_at: int

`cache` Table

- key: varchar(255) (PK)
- value: mediumtext
- expiration: int

📁 File Structure

cca-student-onboarding/
├── app/
│   ├── Console/
│   │   └── Commands/           # Artisan commands
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Admin/
│   │   │   │   ├── AdminDashboardController.php   # Registrations + export/recovery
│   │   │   │   ├── AdminPaymentController.php     # Payment ledger CRUD
│   │   │   │   ├── AdminProgramController.php     # Program + intake management
│   │   │   │   ├── AdminAccountController.php     # Admin account lifecycle
│   │   │   │   ├── AdminActivityController.php    # Activity timeline + export
│   │   │   │   └── AdminAuthController.php        # Admin auth flow
│   │   │   ├── Auth/                             # Authentication controllers
│   │   │   ├── CCARegistrationController.php     # Public registration
│   │   │   └── ProfileController.php             # User profile
│   │   ├── Middleware/
│   │   │   └── AdminAuthenticate.php             # Admin auth middleware
│   │   └── Requests/                             # Form requests
│   ├── Models/
│   │   ├── CCARegistration.php                   # Registration model
│   │   ├── RegistrationPayment.php               # Payment ledger model
│   │   ├── Program.php                           # Program catalog model
│   │   ├── ProgramIntakeWindow.php               # Intake window model
│   │   ├── AdminActivityLog.php                  # Admin audit log model
│   │   └── User.php                              # User model
│   ├── Providers/
│   │   └── AppServiceProvider.php                # Service providers
│   ├── Services/
│   │   ├── FileUploadService.php                 # R2 upload service
│   │   ├── RecaptchaService.php                  # reCAPTCHA verification
│   │   ├── ProgramCatalogService.php             # Program/intake resolution
│   │   ├── PaymentLedgerService.php              # Paid total sync logic
│   │   └── ActivityLogger.php                    # Admin action logging
│   └── View/
│       └── Components/                           # Blade components
├── bootstrap/
│   ├── app.php                                   # Application bootstrap
│   └── providers.php                             # Service providers
├── config/
│   ├── app.php                                   # App configuration
│   ├── database.php                              # Database config
│   ├── filesystems.php                           # R2 configuration
│   ├── programs.php                              # Geographic lists (countries/districts)
│   ├── services.php                              # reCAPTCHA config
│   └── permission.php                            # Spatie permissions
├── database/
│   ├── factories/
│   │   └── UserFactory.php                       # Model factories
│   ├── migrations/                               # Database migrations
│   │   ├── 2025_11_09_213023_create_cca_registrations_table.php
│   │   ├── 2026_02_19_000002_create_registration_payments_table.php
│   │   ├── 2026_02_19_000003_create_programs_table.php
│   │   ├── 2026_02_19_000004_create_program_intake_windows_table.php
│   │   ├── 2026_02_19_000005_add_soft_deletes_to_users_and_cca_registrations.php
│   │   └── 2026_02_19_000006_create_admin_activity_logs_table.php
│   └── seeders/
│       ├── AdminUserSeeder.php                   # Default admin
│       ├── ProgramSeeder.php                     # Program catalog seed
│       ├── RoleSeeder.php                        # Admin role
│       └── DatabaseSeeder.php                    # Master seeder
├── public/
│   ├── images/
│   │   ├── icon.png                              # App icon
│   │   └── logo-wide.png                         # Logo
│   ├── build/                                    # Compiled assets
│   └── index.php                                 # Entry point
├── resources/
│   ├── css/
│   │   └── app.css                               # Main stylesheet
│   ├── js/
│   │   ├── app.js                                # Main JavaScript
│   │   ├── bootstrap.js                          # Bootstrap
│   │   └── file-upload.js                        # File upload handler
│   └── views/
│       ├── cca-register.blade.php                # Registration form
│       ├── welcome.blade.php                     # Landing page
│       ├── admin/
│       │   ├── dashboard.blade.php               # Admin dashboard
│       │   ├── show.blade.php                    # View registration
│       │   ├── edit.blade.php                    # Edit registration
│       │   ├── login.blade.php                   # Admin login
│       │   ├── profile.blade.php                 # Admin profile
│       │   ├── payments/                         # Payment ledger views
│       │   ├── programs/                         # Program/intake views
│       │   ├── accounts/                         # Admin account management views
│       │   ├── activity/                         # Activity timeline views
│       │   ├── layouts/
│       │   │   └── app.blade.php                 # Admin layout
│       │   └── partials/
│       │       └── navigation.blade.php          # Admin nav
│       ├── auth/                                 # Auth views
│       ├── layouts/
│       │   ├── app.blade.php                     # Public layout
│       │   ├── guest.blade.php                   # Guest layout
│       │   └── navigation.blade.php              # Public nav
│       └── profile/                              # Profile views
├── routes/
│   ├── web.php                                   # Web routes
│   ├── auth.php                                  # Auth routes
│   └── console.php                               # Artisan commands
├── storage/
│   ├── app/                                      # Application files
│   ├── framework/                                # Framework files
│   └── logs/                                     # Log files
├── tests/                                        # PHPUnit tests
├── .env.example                                  # Environment template
├── artisan                                       # Artisan CLI
├── composer.json                                 # PHP dependencies
├── package.json                                  # JS dependencies
├── phpunit.xml                                   # PHPUnit config
├── tailwind.config.js                            # Tailwind config
├── vite.config.js                                # Vite config
└── README.md                                     # This file

🔐 Security

Authentication & Authorization

Laravel Breeze - Modern authentication with admin guard separation
Spatie Permissions - Role-based access control (RBAC)
Session Management - Secure session handling with database driver
Remember Me - Optional persistent login with encrypted tokens

Input Validation

Form Requests - Centralized validation rules in CCARegistration model
Custom Rules - NIC/Passport validation, program status check
File Validation - MIME type checking, size limits, extension whitelist
Sanitization - HTML purification, SQL injection prevention

Data Protection

Encryption - Sensitive data encrypted at rest
HTTPS Enforcement - Force SSL in production
Password Hashing - BCrypt with configurable rounds
API Token Security - Sanctum-ready for API authentication

File Security

Cloudflare R2 - Encrypted storage with access controls
Pre-signed URLs - Temporary access with expiration
File Scanning - Ready for antivirus integration
Upload Limits - 10MB per file, configurable

Headers & CORS

X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Strict-Transport-Security: max-age=31536000

Rate Limiting

API Rate Limiting - 60 requests per minute per IP
Login Throttling - Protection against brute force attacks
Registration Throttling - Prevent spam submissions

Security Best Practices Implemented

✅ SQL Injection Prevention (Eloquent ORM) ✅ XSS Protection (Blade escaping) ✅ CSRF Protection (Laravel tokens) ✅ Clickjacking Prevention (X-Frame-Options) ✅ MIME Sniffing Prevention ✅ Input Sanitization ✅ Output Encoding ✅ Secure Password Storage ✅ Session Fixation Prevention ✅ File Upload Security

📡 API Documentation

Public Endpoints

Register Student

POST /cca-register
Content-Type: multipart/form-data

Request Body:

{
  "program_id": "CCA-PM25",
  "full_name": "John Doe",
  "date_of_birth": "1995-01-15",
  "gender": "Male",
  "nic_number": "950151234V",
  "email": "john@example.com",
  "phone_number": "+94771234567",
  "whatsapp_number": "+94771234567",
  "permanent_address": "123 Main St, Colombo",
  "country": "Sri Lanka",
  "province": "Western",
  "district": "Colombo",
  "guardian_name": "Jane Doe",
  "guardian_occupation": "Teacher",
  "guardian_contact": "+94771234568",
  "academic_qualification": "Bachelor's Degree",
  "academic_qualification_documents[]": [File],
  "nic_documents[]": [File],
  "passport_photo": File,
  "payment_slip": File,
  "terms_accepted": true,
  "recaptcha_token": "token_here"
}

Response (Success):

{
    "success": true,
    "message": "Registration submitted successfully!",
    "registration_id": "REG-2025-001234",
    "redirect_url": "/registration-success"
}

Response (Error):

{
    "message": "The given data was invalid.",
    "errors": {
        "program_id": [
            "Registration for Frontend Developer Career Accelerator is currently closed..."
        ]
    }
}

Admin Endpoints

List Registrations

GET /admin/registrations
Authorization: Session Cookie

Query Parameters:
- search: string (optional)
- program_filter: string (optional)
- page: integer (default: 1)

Response:

{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "register_id": "REG-2025-001234",
            "full_name": "John Doe",
            "email": "john@example.com",
            "program_id": "CCA-PM25",
            "program_name": "Project Manager Career Accelerator",
            "phone_number": "+94771234567",
            "created_at": "2025-01-11T10:30:00.000000Z"
        }
    ],
    "total": 150,
    "per_page": 20,
    "last_page": 8
}

View Registration

GET /admin/registrations/{id}
Authorization: Session Cookie

Response:

{
  "id": 1,
  "register_id": "REG-2025-001234",
  "program": {
    "id": "CCA-PM25",
    "name": "Project Manager Career Accelerator",
    "year": "2025",
    "duration": "6 Months"
  },
  "student": {
    "full_name": "John Doe",
    "date_of_birth": "1995-01-15",
    "gender": "Male",
    "nic_number": "950151234V",
    "email": "john@example.com",
    "phone_number": "+94771234567",
    "whatsapp_number": "+94771234567"
  },
  "documents": {
    "passport_photo": {
      "url": "https://r2.../passport_photo.jpg",
      "name": "passport_photo.jpg"
    },
    "payment_slip": {
      "url": "https://r2.../payment_slip.pdf",
      "name": "payment_slip.pdf"
    },
    "academic_documents": [...],
    "nic_documents": [...]
  },
  "payment": {
    "tags": ["General Rate", "Partial Payment"],
    "current_paid_amount": 62500.00
  },
  "created_at": "2025-01-11T10:30:00.000000Z"
}

Update Registration

PUT /admin/registrations/{id}
Authorization: Session Cookie
Content-Type: application/json

Request Body:

{
    "program_id": "CCA-PM25",
    "full_name": "John Doe",
    "email": "john@example.com",
    "phone_number": "+94771234567",
    "tags": ["Full Payment", "General Rate"],
    "current_paid_amount": 125000.0
}

Delete Registration

DELETE /admin/registrations/{id}
Authorization: Session Cookie

Response:

{
    "success": true,
    "message": "Registration deleted successfully"
}

Export to Excel

GET /admin/registrations/export
Authorization: Session Cookie

Query Parameters:
- search: string (optional)
- program_filter: string (optional)

Response: Binary Excel file download

🏆 Best Practices Implemented

Code Quality

✅ PSR-12 Coding Standards - Laravel Pint enforcement ✅ Type Hints - Strict typing throughout ✅ Dependency Injection - Service container usage ✅ Single Responsibility - One purpose per class ✅ DRY Principle - No code duplication ✅ SOLID Principles - Object-oriented best practices ✅ Meaningful Names - Self-documenting code

Database

✅ Migrations - Version-controlled schema ✅ Seeders - Repeatable data population ✅ Eloquent ORM - Query builder with relationships ✅ Indexes - Optimized queries ✅ JSON Columns - Flexible data storage ✅ Soft Deletes Active - Recoverable deletions for registrations and admin users

Frontend

✅ Responsive Design - Mobile-first approach ✅ Progressive Enhancement - Works without JavaScript ✅ Accessibility - WCAG 2.1 Level AA compliant ✅ Performance - Lazy loading, code splitting ✅ SEO Friendly - Semantic HTML, meta tags ✅ Cross-browser - IE11+, Chrome, Firefox, Safari, Edge

Security

✅ Least Privilege - Minimal permissions ✅ Defense in Depth - Multiple security layers ✅ Input Validation - Never trust user input ✅ Output Encoding - Prevent XSS ✅ Error Handling - No sensitive data in errors ✅ Audit Logging Active - Timeline of admin actions with before/after snapshots

Performance

✅ Query Optimization - Eager loading, indexes ✅ Caching - Database cache driver ✅ Asset Optimization - Vite bundling, minification ✅ CDN Ready - Static assets servable from CDN ✅ Database Pooling - Connection reuse ✅ Queue System - Background job processing

Testing

✅ Unit Tests Ready - PHPUnit configured ✅ Feature Tests Ready - HTTP testing ✅ Factory Pattern - Test data generation ✅ Continuous Integration Ready - CI/CD compatible

Documentation

✅ Inline Comments - Complex logic explained ✅ PHPDoc Blocks - All classes and methods ✅ README.md - Comprehensive documentation ✅ API Documentation - Endpoint specifications ✅ Changelog Ready - Version tracking

🚀 Deployment

Production Checklist

Pre-deployment

Optimization

# Optimize application
php artisan config:cache
php artisan view:cache

# Build production assets
npm run build

# Optimize Composer autoloader
composer install --optimize-autoloader --no-dev

Note: Skip php artisan route:cache while closure routes exist in routes/web.php.

cPanel Git Deployment (Shared Hosting)

Ensure .cpanel.yml exists at repository root.
Keep .env on server (do not commit to Git).
Commit public/build assets for environments where server-side Node build is unreliable.
Set domain document root to /public.
Deploy flow:
1. Push branch to GitHub
2. Update from Remote in cPanel Git
3. Deploy HEAD Commit

Server Configuration

Nginx Example:

server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name yourdomain.com;
    root /var/www/cca-student-onboarding/public;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }

    client_max_body_size 20M;
}

Apache Example (.htaccess):

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

<IfModule mod_headers.c>
    Header set X-Frame-Options "DENY"
    Header set X-Content-Type-Options "nosniff"
    Header set X-XSS-Protection "1; mode=block"
    Header set Referrer-Policy "strict-origin-when-cross-origin"
</IfModule>

php_value upload_max_filesize 20M
php_value post_max_size 20M
php_value max_execution_time 300

Queue Worker Setup

Systemd Service (/etc/systemd/system/cca-queue.service):

[Unit]
Description=CCA Queue Worker
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/cca-student-onboarding
ExecStart=/usr/bin/php /var/www/cca-student-onboarding/artisan queue:work --sleep=3 --tries=3 --max-time=3600
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl enable cca-queue
sudo systemctl start cca-queue

Cron Jobs

Add to crontab:

* * * * * cd /var/www/cca-student-onboarding && php artisan schedule:run >> /dev/null 2>&1

Monitoring

Laravel Telescope (Development):

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

Log Monitoring:

# Real-time logs
php artisan pail

# Or use tail
tail -f storage/logs/laravel.log

Hosting Providers

Recommended:

DigitalOcean - App Platform or Droplets
AWS - Elastic Beanstalk or EC2
Cloudways - Managed Laravel hosting
Laravel Forge - Automated deployment
Ploi - Server management
Heroku - Quick deployment
Shared Hosting - With SSH access

🔧 Troubleshooting

Common Issues

File Upload Errors

Problem: Files fail to upload to R2

Solution:
1. Check R2 credentials in .env
2. Verify bucket CORS settings
3. Check file size limits in php.ini
4. Review storage/logs/laravel.log

reCAPTCHA Verification Fails

Problem: "Could not verify that you are human"

Solution:
1. Verify site key in .env matches domain
2. Check RECAPTCHA_SITE_KEY and RECAPTCHA_SECRET_KEY
3. Ensure domain is registered in Google reCAPTCHA console
4. Check score threshold (default 0.5)
5. Clear cache: php artisan config:clear

Admin Can't Login

Problem: "These credentials do not match our records"

Solution:
1. Verify admin user exists: php artisan tinker, User::where('email', 'admin@cca.it')->first()
2. Check admin role: php artisan tinker, User::first()->hasRole('admin')
3. Reset password: php artisan tinker, User::first()->update(['password' => bcrypt('newpassword')])
4. Run seeders: php artisan db:seed --class=RoleSeeder && php artisan db:seed --class=AdminUserSeeder

Permission Denied Errors

Problem: "The stream or file could not be opened"

Solution:
# Linux/Mac
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

# Development
chmod -R 777 storage bootstrap/cache

Database Connection Failed

Problem: "SQLSTATE[HY000] [1045] Access denied"

Solution:
1. Verify database credentials in .env
2. Test connection: php artisan tinker, DB::connection()->getPdo()
3. Check MySQL service: sudo systemctl status mysql
4. Create database: mysql -u root -p, CREATE DATABASE your_database;
5. Grant permissions: GRANT ALL PRIVILEGES ON your_database.* TO 'user'@'localhost';

404 Not Found

Problem: Routes not working

Solution:
1. Check .htaccess exists in public/
2. Enable mod_rewrite: sudo a2enmod rewrite && sudo systemctl restart apache2
3. Clear route cache: php artisan route:clear
4. Check DocumentRoot points to public/ directory

WhiteScreen / 500 Error

Problem: Application shows blank page

Solution:
1. Enable debug: Set APP_DEBUG=true in .env (temporarily)
2. Check logs: storage/logs/laravel.log
3. Clear all caches: php artisan optimize:clear
4. Check file permissions
5. Verify .env file exists and is valid

Slow Performance

Problem: Application loading slowly

Solution:
1. Enable caching: php artisan config:cache && php artisan view:cache
2. Optimize autoloader: composer dump-autoload -o
3. Use queue for heavy tasks
4. Enable OPcache in php.ini
5. Use database indexes
6. Implement Redis/Memcached

Debug Mode

Enable Detailed Errors (Development Only):

APP_DEBUG=true
APP_ENV=local
LOG_LEVEL=debug

Disable in Production:

APP_DEBUG=false
APP_ENV=production
LOG_LEVEL=error

Getting Help

Check Logs:

tail -f storage/logs/laravel.log
php artisan pail

Clear All Caches:
```
php artisan optimize:clear
```

Run Diagnostics:

php artisan about
php artisan config:show database
php artisan route:list

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Getting Started

Fork the Repository

git clone https://github.com/yourusername/cca-student-onboarding.git
cd cca-student-onboarding
git remote add upstream https://github.com/original/cca-student-onboarding.git

Create Feature Branch
```
git checkout -b feature/amazing-feature
```
Make Changes
- Follow PSR-12 coding standards
- Write tests for new features
- Update documentation
- Commit with clear messages
Test Your Changes
```
composer test
php artisan test
```
Submit Pull Request
- Push to your fork
- Create PR with clear description
- Reference any related issues

Coding Standards

PHP (PSR-12):

composer pint

JavaScript (Prettier):

npm run format

Commit Messages:

feat: Add payment tracking feature
fix: Resolve file upload issue on Safari
docs: Update installation instructions
style: Format code with Pint
refactor: Improve registration controller
test: Add unit tests for RecaptchaService
chore: Update dependencies

Pull Request Process

Update README.md with details of changes
Update CHANGELOG.md following Keep a Changelog
Increase version numbers following Semantic Versioning
PR will be merged after review by maintainers

Code of Conduct

Be respectful and inclusive
Accept constructive criticism gracefully
Focus on what's best for the community
Show empathy towards others

📄 License

This project is licensed under the MIT License - see below for details:

MIT License

Copyright (c) 2025 Codezela Career Accelerator

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

💬 Support

Documentation

Official Laravel Docs: https://laravel.com/docs
Tailwind CSS Docs: https://tailwindcss.com/docs
Alpine.js Docs: https://alpinejs.dev/start-here

Community

GitHub Issues: Report bugs and request features
Email Support: info@codezela.com
Stack Overflow: Tag questions with cca-portal

Commercial Support

For enterprise support, custom development, and training:

Email: info@codezela.com
Website: https://codezela.com
Phone: +94 72 733 3577

FAQ

Q: Can I use this for my own institution? A: Yes! This is open-source under MIT license. Feel free to customize for your needs.

Q: Is this production-ready? A: Yes! This application follows enterprise-level best practices and security standards.

Q: Can I contribute? A: Absolutely! We welcome contributions. See Contributing section.

Q: What's the difference between R2 and S3? A: R2 is Cloudflare's S3-compatible storage with zero egress fees. The app works with both.

Q: How do I add more programs? A: Use Admin → Program Management (/admin/programs) to create/update programs and intake windows. config/programs.php is only for countries/districts now.

Q: Can I use a different payment gateway? A: Yes! The payment slip is currently manual upload. You can integrate any gateway.

Q: Is multi-language support available? A: Not yet, but Laravel's localization features make it easy to add.

Q: Can I self-host without cloud services? A: Yes! Use local filesystem instead of R2, and remove reCAPTCHA if needed.

🌟 Acknowledgments

Built With

Laravel - The PHP Framework For Web Artisans
Tailwind CSS - A utility-first CSS framework
Alpine.js - Your new, lightweight, JavaScript framework
Three.js - JavaScript 3D Library
Spatie Laravel Permission - Associate users with roles and permissions

Inspiration

Laravel Breeze - Authentication scaffolding
Modern web design trends
Educational institution portals

📊 Project Stats

🗺 Roadmap

Version 2.0 (Planned)

Email notifications (registration confirmation, admin alerts)
SMS notifications (SMS gateway integration)
Payment gateway integration

🎉 Thank you for using CCA Student Onboarding Portal!

Made with ❤️ by the Codezela Team

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 64 Commits
app		app
bootstrap		bootstrap
config		config
database		database
public		public
resources		resources
routes		routes
storage		storage
tests		tests
.cpanel.yml		.cpanel.yml
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
NEXTJS16_NEW_APP_SPEC.md		NEXTJS16_NEW_APP_SPEC.md
README.md		README.md
artisan		artisan
composer.json		composer.json
composer.lock		composer.lock
package-lock.json		package-lock.json
package.json		package.json
phpunit.xml		phpunit.xml
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
vite.config.js		vite.config.js

codezelat/cca-student-onboarding

Folders and files

Latest commit

History

Repository files navigation

🎓 Codezela Career Accelerator (CCA) - Student Onboarding Portal

📋 Table of Contents

🌟 Overview

Key Highlights

Recent Platform Updates (February 19, 2026)

✨ Features

🎓 Student Features

Registration System

Document Management

User Experience

👨‍💼 Admin Features

Dashboard

Registration Management

Admin Operations

Document Viewer

User Management

🔒 Security Features

Protection Layers

Data Privacy

🛠 Tech Stack

Backend

Frontend

Cloud Services

Development Tools

💻 System Requirements

Minimum Requirements

Recommended Server Specifications

PHP Extensions Required

🚀 Installation

Quick Start

Detailed Installation

1. Clone Repository

2. Install PHP Dependencies

3. Install Node Dependencies

4. Environment Configuration

5. Configure Environment Variables

6. Database Setup

7. Storage Setup

8. Build Assets

9. Set Permissions

10. Start Application

⚙️ Configuration

Programs Configuration

Cloudflare R2 Setup

Google reCAPTCHA Setup

Admin User Creation

Email Configuration

📖 Usage

For Students

1. Access Registration Form

2. Complete Form Sections

3. Submit Registration

For Administrators

1. Login

2. Dashboard Overview

3. View Registration Details

4. Document Viewing

5. Edit Registration

6. Manage Payments

7. Delete / Restore Registration

8. Manage Programs / Intakes

9. Manage Activity Timeline

10. Manage Profile

🎛 Admin Panel

Dashboard Features

Statistics Cards

Filtering & Search

Registration Table

Payment Management

Payment Ledger

Backward Compatibility

Document Management

Document Viewer Features

Supported File Types

🗄 Database Schema

`users` Table

`cca_registrations` Table

`roles` & `permissions` Tables

`jobs` Table

`cache` Table