# Mavela School Management System

Mavela is a PHP 8 / MySQL school platform covering administration, teaching,
learner and parent access, finance, ancillary staff, HOP workflows, e-learning,
school assets, inventory, tuckshop/produce sales, timetables, and school events.

## Main capabilities

- Role-based dashboards for administrators, HOPs, teachers, accountants,
  ancillary staff, learners, and parents
- Admissions, learner records, parent linking, transfers, and annual promotion
- Marks capture, report cards, attendance, e-learning, and e-library resources
- Fee invoices, receipts, ledger cards, expenses, exchange rates, and payroll
- Staff profiles, leave, assignments, workload, and document review
- Announcements and optional WhatsApp notifications
- Inventory and assets plus a modern Tuckshop/Produce POS with barcode search, held orders, discounts, multi-currency payments, cashier shifts, stock audit, receipts, reports, and controlled transaction voids
- Shared weekly class timetable and academic events calendar
- School branding, responsive screens, searchable menus, dark mode, and
  accessibility controls

## Requirements

- PHP 8.1 or newer with PDO MySQL, Fileinfo, cURL, and GD extensions
- MySQL 8+ or MariaDB 10.5+
- Apache 2.4 with `.htaccess` enabled (recommended)
- HTTPS for every production deployment

## Secure installation

1. Create an empty MySQL database and a dedicated database user.
2. Copy `config.local.example.php` to `config.local.php`.
3. Enter the database credentials in `config.local.php`.
4. Keep `config.local.php` out of Git and backups shared with other people.
5. Upload the project and browse to `index.php`.
6. On an empty database, the secure setup screen creates the first
   administrator. No production default password is generated.
7. Import `DB/mavela_db.sql` only when restoring the included database snapshot.

Environment variables can be used instead of `config.local.php`:

```text
MAVELA_APP_ENV=production
MAVELA_DB_HOST=localhost
MAVELA_DB_NAME=database_name
MAVELA_DB_USER=database_user
MAVELA_DB_PASS=unique_database_password
MAVELA_TIMEZONE=Africa/Harare
MAVELA_TRUST_PROXY=0
MAVELA_DEMO_MODE=0
```

Set `MAVELA_TRUST_PROXY=1` only when the application is behind a trusted reverse
proxy that replaces forwarded-IP headers. Demo accounts and sample products are
created only on a local installation or when `MAVELA_DEMO_MODE=1`.

## Upgrading an existing installation

1. Export a full database backup in phpMyAdmin.
2. Back up `Uploads/` and your existing `config.local.php`.
3. Replace application files, preserving those two items.
4. Open `index.php` and sign in. Security, workflow and modern POS tables/columns are
   added idempotently when needed.
5. In Admin, open **Business Accounts** and replace any old shared
   tuckshop/produce credentials.
6. Ask every user who had a known demo/default password to change it.
7. Rotate the production database password that existed in earlier copies of
   `Config.php`, then update only `config.local.php`.

## Security behavior

- CSRF tokens protect all POST forms.
- Sessions use strict, HTTP-only, SameSite cookies and regenerate on login.
- Repeated failed logins are rate-limited.
- New staff receive unique one-time temporary passwords.
- Uploads are checked by extension, size, and detected content type.
- PHP execution is denied inside `Uploads/`.
- Database dumps, configuration, logs, documentation, and directory listings
  are blocked from web access.
- Technical database errors are logged in production instead of displayed.

## Operations

- Take encrypted off-server database and `Uploads/` backups every day.
- Test a restore at least once per school term.
- Use separate database credentials for testing and production.
- Keep PHP, MySQL, and the hosting control panel patched.
- Review Admin → System Log and suspend unused business accounts.
- Do not keep learner records or financial exports on shared devices.

## Verification

Before deployment, run:

```bash
find . -maxdepth 1 -name '*.php' -print0 | xargs -0 -n1 php -l
```

Then test login, role redirects, admissions, attendance, marks, payment entry,
report generation, file uploads, the academic planner, mobile navigation, and the
Tuckshop/Produce POS checkout, held-order, receipt, shift, stock adjustment and
void workflows against a staging database. See `MODERN_POS_UPGRADE.md`.
