EduDesk School
Management System

⚡ Quick Start

Get EduDesk running in under 10 minutes. No CLI required for the basic setup.

Worker (Emails, SMS, Webhooks)

# Add to cPanel cron jobs (every minute)
* * * * * /usr/bin/php /home/user/public_html/worker.php

# Or run directly
php worker.php

Daily Cron (Reminders, Trial Warnings, Reports)

# Run once per day at 7 AM
0 7 * * * /usr/bin/php /home/user/public_html/cron/daily.php

📋 Overview

EduDesk is a production-grade, multi-tenant school management SaaS built on PHP 8.3 and MySQL 8. It ships as a single-page web application (SPA) with no JavaScript framework dependency — no React, no Vue, no Node.js runtime required.

From K–12 schools in emerging markets to international private schools requiring SAML SSO and GDPR compliance, EduDesk covers the full spectrum. Its open PHP architecture means it runs on any shared hosting, VPS, or cloud environment without a build step.

Who It's For

• Small schools (50–500 students) — Affordable, full-featured management out of the box
• Large institutions (500–5,000 students) — Enterprise SSO, SAML, audit logs, API access
• SaaS operators — White-label, multi-school superadmin console, plan-based billing
• Developers / resellers — REST API, webhooks, API keys, OpenAPI spec

📊 Honest SaaS Score Card

An honest internal assessment of where EduDesk v1 stands as an enterprise SaaS platform. Last reviewed: May 2026 — updated after latest UX & stability sprint.

Score Notes

Still Missing for a True 10/10

Previously Missing — Now Built ✅

⚙️ Requirements

🚀 Installation

1. Upload Files

   Extract the archive and upload all files to your web root (public_html/) via FTP or cPanel File Manager.

2. Create a MySQL Database

   In cPanel → MySQL Databases, create a database + user with All Privileges. Note the credentials.

3. Open the Setup Wizard

   Navigate to your domain. You'll be redirected to setup.php automatically. The 4-step wizard installs all tables and writes config/config.php.

4. Configure School & Admin

   Enter school name, academic terms, fee structure defaults, and create your first superadmin account (min. 8-character password).

5. Run Migrations

   Visit /migrate_all.php once to apply all schema upgrades. This is idempotent — safe to re-run.

6. Configure Stripe (SaaS mode)

   In config/config.php add your STRIPE_WEBHOOK_SECRET. In Settings → Billing, add your Stripe keys.

7. Start the Worker

   For email delivery, webhook dispatch, and SMS: * * * * * php /path/to/worker.php

📁 File Structure

🎓 Academic Modules

💰 Finance & Fees

📱 Communication

🏢 Enterprise Features

☁️ SaaS & Billing

🔧 Developer Tools

REST API (v1)

🔐 Roles & Permissions

⚙️ Settings Reference

Settings are stored as a JSON blob in the settings table, scoped per school_id. All keys below are writable via the Settings API. Arbitrary key injection is blocked server-side via a whitelist of ~70 allowed keys.

School Identity

Academic

🔑 Environment Variables

These constants are set in config/config.php (written by the setup wizard). You can also set them as actual environment variables and read them via getenv() for containerized deployments.

🔒 Security

Authentication

• PHP sessions with session_regenerate_id(true) on login
• Session fingerprinting (IP + User-Agent hash) to detect hijacking
• Idle timeout (configurable, default 60 min)
• CSRF double-submit tokens on all state-changing requests
• Passwords: password_hash(PASSWORD_BCRYPT), min 8 chars
• 2FA: TOTP (RFC 6238), QR-code enrollment, backup codes

Application Security

• All DB queries use PDO prepared statements — SQL injection impossible
• All output uses htmlspecialchars() — XSS mitigated
• Settings API: server-side whitelist of ~70 allowed keys
• File uploads: MIME type + extension validation, stored outside webroot
• Webhook secrets: stored as SHA-256 hash, never in job payloads
• API keys: stored as hashed prefix, raw key shown once only

Rate Limiting

• Login page: 10 attempts / 15 min per IP
• Superadmin login: 5 attempts / 15 min per IP
• Password reset: 3 requests / 30 min per email
• REST API: 300 req / min per API key
• Parent login: 5 attempts / 15 min per IP

Nginx Configuration

# Block protected directories
location ~ ^/(config|includes|lang)/(.*\.php)$ {
    deny all; return 404;
}
location ~ /\. { deny all; }

# Security headers
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header Referrer-Policy strict-origin-when-cross-origin;

⏰ Cron & Background Worker

EduDesk has two background processes: the worker (processes jobs from the queue) and the daily cron (time-sensitive tasks like reminders and reports).

Worker (worker.php)

Processes email delivery, SMS sending, and webhook dispatch. Should run every minute.

# cPanel cron — every minute
* * * * * /usr/bin/php /path/to/worker.php >/dev/null 2>&1

# With Redis (recommended): BLPOP-based, near-instant dispatch
# Without Redis: polls job_queue table every 5 seconds

Daily Cron (cron/daily.php)

Run once per day — typically at 7–8 AM school time. Handles the following tasks:

# cPanel cron — daily at 7 AM
0 7 * * * /usr/bin/php /path/to/cron/daily.php >/dev/null 2>&1

🌐 REST API v1

The v1 REST API enables third-party integrations. All requests require a Bearer API key created from the admin dashboard (Settings → API Keys).

# Authentication
Authorization: Bearer edu_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Base URL
https://yourdomain.com/api/v1/

# OpenAPI docs (interactive)
https://yourdomain.com/api/v1/docs.php?ui

🔗 Webhooks

Configure outbound webhooks from Settings → Webhooks. EduDesk will POST to your HTTPS endpoint whenever a subscribed event fires.

Request Format

{
  "event": "student.created",
  "school_id": "abc123",
  "timestamp": 1700000000,
  "data": { ... }
}

Signature Verification

# Header sent with every request:
X-EduDesk-Signature: sha256=<hmac_hex>

# Verify in PHP:
$expected = hash_hmac('sha256', $rawBody, $secret);
hash_equals($expected, $receivedSig); // true = authentic

Supported events: student.created, student.updated, student.deleted, fee.paid, attendance.marked, exam.scored, teacher.created, report.generated, ping (test).

Retry policy: 3 attempts with exponential backoff. Failed deliveries move to dead-letter queue, visible in the webhook delivery log.

🗄️ Database Schema

migrate_all.php is the canonical migration runner — idempotent, safe to re-run. It installs and upgrades all tables across 28 migration groups (A through CC).

Core Tables

🔧 Troubleshooting

Most issues fall into one of these categories. Check them in order before posting a support ticket.

1. "Table doesn't exist" / SQL errors on first load

2. Blank page / 500 error after upload

• Check PHP version: must be 8.0+. In cPanel → PHP Selector, confirm the active version.
• Check PHP extensions: PDO, PDO_MySQL, JSON, mbstring, openssl, curl must all be enabled.
• Check file permissions: config/, uploads/ should be writable (755 directories, 644 files).
• Enable error display temporarily: add ini_set('display_errors',1); at the top of index.php.

3. Login redirects back to login page

• Sessions not persisting — check that PHP session save path is writable.
• Cookie domain mismatch — if on a subdomain, ensure session.cookie_domain is set correctly.
• HTTPS/HTTP mismatch — if APP_URL uses https but you're on http, session cookie flags won't match.

4. Emails not sending

• Worker not running — confirm worker.php cron is active. Check the job_queue table for stuck jobs.
• SMTP credentials wrong — use Settings → Email → Send Test Email to verify.
• Gmail blocking — enable "Less secure apps" or use an App Password with 2FA-enabled accounts.
• Port blocked by host — try port 465 (SSL) or 587 (TLS) if 25 is blocked.

5. SMS not sending

• Check gateway selection in Settings → SMS. Confirm your API key has credit/balance.
• Phone numbers must include country code (e.g. +233xxxxxxxxx for Ghana).
• For Africa's Talking sandbox mode, numbers must be in your sandbox whitelist.
• Check sms_logs table for error responses from the gateway.

6. Webhooks not delivering

• Endpoint must be HTTPS with a valid SSL certificate (self-signed certs are rejected).
• Private IP addresses (192.168.x.x, 10.x.x.x) are blocked for SSRF protection.
• Your endpoint must respond with HTTP 200 within 10 seconds, or it's marked as failed.
• Check webhook_deliveries table for the exact response code and body.

7. PDF / Report cards not generating

• EduDesk uses PHP's built-in HTML output for print-optimized PDFs. Enable the browser's "Print to PDF" option.
• If using a third-party PDF library (Dompdf/mPDF add-on), ensure the library files are uploaded and permissions are correct.

8. "APP_SECRET is too short" warning

9. Superadmin can't log in

• Superadmin uses a separate login at /superadmin/ — not the same as the school admin login.
• Credentials are set in config/config.php as SUPERADMIN_EMAIL and SUPERADMIN_PASS.
• Rate limit: 5 failed attempts locks the IP for 15 minutes.

10. Migration fails partway through

• All migration steps use IF NOT EXISTS — re-running is safe.
• If a step fails due to a missing column dependency, run the migration twice (second run fills gaps).
• For a fresh database, migrations run cleanest from an empty schema rather than upgrading from a very old version.

📝 Changelog

❓ FAQ

💬 Support

What's Included in Support

• ✅ Feature questions and usage guidance
• ✅ Installation help on standard hosting
• ✅ Bug fixes for issues in the delivered code
• ✅ Security issue reports (treated with priority)
• ❌ Custom development / feature additions (available as paid service via Nubrix Technologies)
• ❌ Support for heavily modified installations