# Skulitech ERP

> **cPanel-ready release:** Start with `CPANEL_DEPLOYMENT.md`. The ZIP is designed for extraction directly into a domain, subdomain or subfolder document root. Windows/XAMPP instructions remain available in `README_XAMPP.txt` for local testing.

Skulitech ERP is an integrated institutional management system for admissions, student records, academics, examinations, finance, human resources, procurement, library services, clearance, reporting and role-based portals.


### Upload validation and appointment letters (2026-07-24)

- General document, assignment, learning-resource and portfolio evidence uploads now accept only PDF, JPG/JPEG, PNG, DOC and DOCX files, with server-side extension and MIME validation.
- Structured CSV/XLSX imports remain available only in dedicated import workflows such as students, courses, finance schedules and procurement requisitions.
- Appointment letters now use the heading `APPOINTMENT TO THE ROLE OF [DESIGNATION]`.
- The appointment details table has been removed from printed appointment letters.
- Appointment letters include an editable, role-specific `Roles and Responsibilities` section rendered as a numbered list.
- Run migration `20260724_010_upload_validation_and_appointment_roles.sql` before using the updated HR letter form.

## Production installation

1. Create a MySQL/MariaDB database and user in cPanel, assign **ALL PRIVILEGES**, and import `database/schema/college_erp_current.sql` in phpMyAdmin.
2. Copy `config/local.example.php` to `config/local.php` and enter the cPanel-prefixed database credentials and a strong `setup_key`.
3. Open `cpanel_setup.php`. It applies pending migrations and creates the first System Administrator using credentials you choose.
4. Delete `cpanel_setup.php` immediately after setup.
5. For upgrades, preserve `config/local.php`, upload the changed files, then run `php bin/migrate.php` and `php bin/check_integrity.php` from cPanel Terminal.
6. Use PHP 8.1 or newer, force HTTPS, and keep `SKULITECH_RUNTIME_SCHEMA_SYNC` disabled in production.

The production package does not bundle a predictable administrator password or a MySQL root configuration. See `CPANEL_DEPLOYMENT.md` for the full checklist.

## Security controls in this release

- MIME-validated, size-limited and randomly named image uploads
- Script execution disabled in upload folders
- Protected database, migration, storage, configuration and documentation folders
- Secure session-cookie defaults and central security headers
- Cryptographically random application numbers, status lookup by phone/KCSE index/application reference, IP/identifier throttling and honeypot protection
- Secure non-expiring signed admission-letter print links for approved applications
- Header-only API token authentication
- Unified password policy and random temporary passwords
- User deactivation instead of destructive account deletion
- CSRF-protected state-changing actions in timetable, academics, admissions, examinations and lecturer allocation workflows

## Academic and assessment flow

The academic structure follows:

`Academic year → session → course module → class → curriculum unit → lecturer assignment → student enrolment → marks → grading → progression`

Teachers select an assigned class and subject/unit, then enter marks for the complete class. The selected subject remains clearly visible, and results, marksheets, transcripts, analytics and progression use the same configurable competency pass mark.


## Sponsor funds, bulk receipting and accrual accounting

The Finance portal supports HELB, County bursaries, NG-CDF/CDF bursaries, scholarships and other sponsor payments. The feature is visible under **Finance → Bulk Sponsor Receipting**, **Sponsor Receipts**, **Bulk Student Allocations** and **Sponsor Control Reports**.

The workflow records one actual bank transfer or cheque acknowledgement. The student allocation schedule is optional when the funding-agency receipt is captured: Finance may attach a CSV/Excel schedule immediately, allocate students one by one, or approve the parent receipt first and allocate it later. A cheque may remain **Pending Clearance** until it appears in the institution bank account. Only a cleared and approved sponsor receipt posts to the bank ledger. Student allocations are non-cash credits linked to that parent receipt, so bank and cashier collections are not duplicated.

Sponsor awards may be recognised as accrued receivables where appropriate. Receipts, allocations and reversals post balanced general-ledger journals, and the sponsor control report reconciles opening unallocated funds, receipts, student allocations and closing unallocated funds. The system also prints a batch register and separate non-cash student allocation advices. See `docs/SPONSOR_FUNDS_AND_ACCRUAL_ACCOUNTING.md`.

No-double-receipting controls reserve each bank, cheque or M-Pesa reference across both sponsor and direct-student receipt ledgers. The direct fee-payment screen rejects sponsor payer descriptions, requires confirmation that the payment is new money, blocks an exact student/amount match against a recent posted sponsor allocation, and prevents official cash-receipt printing for non-cash allocations. Possible historical parent-and-child matches are listed under **Sponsor Control Reports** for reversal and audit review.

## Database management

Numbered migrations are stored in `database/migrations`. Do not edit a migration after it has been applied; create a new numbered migration instead. Diagnostic snapshots are stored privately under `storage/private/snapshots` and are not a substitute for full database backups. Create a compressed full backup with `php bin/backup_database.php`; set `SKULITECH_BACKUP_KEY` to encrypt it. Check each file with `php bin/verify_backup.php /path/to/backup` and complete final recovery verification by restoring into a separate staging database.

## Local assets and offline use

Bootstrap, Bootstrap Icons and jQuery are bundled under `assets/vendor`, so core pages and printable documents do not depend on an external CDN.

## Branding

Institution logos, application backgrounds, letterheads, theme colours and financial-document footers are managed in **Institution Settings**. The bundled Skulitech images remain available under `uploads/logos`.

## Portfolio of Evidence module

The integrated **Portfolio of Evidence** module stores marked examination scans, practical-assessment photographs and supporting documents against each student's registered unit.

- Students can upload and view evidence linked to their own account.
- Lecturers, examination officers, admissions staff or other roles can be granted `portfolio_view`, `portfolio_upload`, `portfolio_review` and `portfolio_manage` from **Settings & Security → Privileges**.
- Evidence files are stored in `storage/private/portfolio` and are served only through an authenticated access-controlled endpoint.
- The module is linked from the sidebar, Student Portal registered units, and Marks Entry student rows.
- Database tables are created automatically on first request. The optional migration is `database/migrations/20260724_007_portfolio_of_evidence.sql`.

## Enterprise finance and procurement controls — July 2026

The Finance and Procurement portals now provide an integrated source-to-pay and accrual-control workflow: unallocated receipts, budget commitments, journal sealing, bank reconciliation structures, three-way supplier matching, fixed assets, period-close preflight checks, annual procurement plans, RFQs/tenders, quotation scoring, contracts, controlled LPO approval, line-level GRNs, stores, supplier scorecards and maker-checker payment vouchers.

Run `php bin/migrate.php` and then `php bin/check_integrity.php` after deployment. Full implementation and operating guidance is in `docs/ENTERPRISE_FINANCE_AND_PROCUREMENT_UPGRADE_2026-07-24.md`.

## Payments, expenses and payroll controls — July 2026

The system now adds the missing staff expense-claim workflow, recurring expenses, accrual/prepayment schedules, controlled petty cash, payroll batches, pre-payroll validation, maker-checker approval, payroll locking, effective-dated statutory rules, automatic payroll ledger posting, salary settlement, statutory remittances and CSV payment schedules. Payroll captures approved overtime, arrears, final dues, unpaid leave, loan/advance recovery, pension, SACCO and court-order deductions. Existing supplier payment vouchers, imprests, sponsor receipts, student payments and procurement controls remain the authoritative workflows and were linked rather than duplicated. Posted entries in the existing Income and Expense registers are corrected through an automatic reversal plus replacement entry; their original rows and journals are no longer overwritten or deleted.

Run `php bin/migrate.php` to apply `20260724_011_payments_expenses_payroll_controls.sql`, followed by `php bin/check_integrity.php`. Full operating guidance is in `docs/PAYMENTS_EXPENSES_PAYROLL_CONTROLS_UPGRADE_2026-07-24.md`.

## Controlled supplier payment vouchers (July 2026)
Supplier payment vouchers now follow a separated Prepare → Check → Approve → Pay workflow. The preparer, checker, approver and payment releaser cannot be the same user at incompatible stages. Every voucher has a branded Print / Save PDF form showing supplier and source-document details, gross amount, deductions, net amount in words, cashbook account, payment reference, document checklist and officer authorisations. Unpaid vouchers carry a NOT PAID watermark and all printing is audited.

## Online Approval Workflows Upgrade (31 July 2026)

This release adds configurable online approvals for procurement requisitions, supplier payment vouchers, imprests and fee-payment corrections, plus full student profile tabs. See `ONLINE_APPROVALS_UPGRADE_2026-07-31.md` for deployment and testing instructions. Existing installations must import `database/upgrades/Skulitech_ERP_Online_Approvals_Database_Upgrade_2026-07-31.sql.gz` once through phpMyAdmin.
