# SMS ERP — Multi-Branch School Management System

A modern, enterprise-grade school ERP built on **Laravel 12 / PHP 8.2+ / MariaDB**,
with a **Bootstrap 5** admin UI, DataTables, Select2 and Chart.js.

One **School** → many **Branches** → **Families** → **Students**. Every major record
belongs to a branch, and access is scoped to the branch(es) a user is assigned to.

---

## Tech stack

| Layer | Choice |
|-------|--------|
| Framework | Laravel 12.62 |
| PHP | 8.2+ |
| Database | MariaDB 10.4 (MySQL-compatible) |
| Auth / RBAC | Custom auth + `spatie/laravel-permission` |
| Audit | `spatie/laravel-activitylog` + `created_by`/`updated_by` columns |
| UI | Bootstrap 5, Bootstrap Icons, DataTables, Select2, Chart.js (CDN) |

## Architecture

```
app/
├── Http/Controllers/         thin controllers → services
├── Http/Requests/            FormRequest validation
├── Services/                 business rules + transactions (BaseService)
├── Repositories/
│   ├── Contracts/            RepositoryInterface
│   └── Eloquent/             BaseRepository + concrete repos
├── Models/
│   ├── Concerns/             BelongsToBranch, HasAuditColumns
│   └── Scopes/               BranchScope (global multi-branch filter)
├── Policies/                 BranchPolicy (+ auto-discovered)
└── Support/                  BranchContext (active-branch resolver)
```

**Multi-branch scoping** — any model that `use BelongsToBranch` is automatically:
- filtered to the active branch on every query (`BranchScope`), and
- stamped with the active `branch_id` on create.

A **Super Admin** sees all branches and can pin one via the navbar **branch switcher**;
every other role is locked to their assigned branch.

## Getting started

```bash
# 1. Database (XAMPP MariaDB) — a database named `sms_erp` (utf8mb4) must exist

# 2. Install + migrate + seed
composer install
php artisan migrate:fresh --seed

# 3. Run
php artisan serve         # http://127.0.0.1:8000
```

> On this machine, invoke PHP/Composer with the XAMPP binary, e.g.
> `& "B:\xampp\php\php.exe" artisan serve --port=8000`.

## Demo accounts (password: `password`)

| Email | Role | Branch |
|-------|------|--------|
| superadmin@school.test | Super Admin | all |
| admin@school.test | School Admin | Main |
| principal@school.test | Principal | Main |
| accountant@school.test | Accountant | Main |
| reception@school.test | Receptionist | Main |
| hr@school.test | HR Manager | Main |
| teacher@school.test | Teacher | Girls |

## Roadmap

- ✅ **Phase 1** — Authentication, Roles & Permissions, Branch Management (done)
- ✅ **Phase 2** — Families, Academic structure, Students, **Student 360° profile**,
  documents, Inquiries & Admissions (register → approve → enroll) (done)
- ✅ **Phase 3** — Academic management (sessions, classes + sections, subjects,
  subject/teacher allocation) and Attendance (student & teacher marking + monthly reports) (done)
- ✅ **Phase 4** — Fee Management: fee types, per-class fee structure, **sibling-discount
  engine**, scholarships/concessions (incl. free students), **combined family challans**,
  collection (partial/full, auto status), printable challan, defaulters, finance dashboard (done)
- ✅ **Phase 5** — Accounting: double-entry chart of accounts, journal entries, income/expense
  vouchers, **fee collections auto-post to the ledger**, General Ledger, Cash/Bank Book,
  Trial Balance, Profit & Loss, Balance Sheet (done)
- ✅ **Phase 6** — Examinations: exams (types/publish), exam papers, grade scale, marks entry,
  **result engine** (percentage, grade, GPA, pass/fail, class position), result cards (printable),
  gazette/tabulation sheet, position holders, subject analysis (done)
- ✅ **Phase 7** — Parent Portal: parent login linked to a family (role-aware redirect, dedicated
  portal layout), dashboard, child attendance, published results/result cards, family fee status,
  notice board (admin CRUD + audience-scoped parent view), family profile (done)
- ✅ **Phase 8** — LMS: teachers post homework/assignments/notes per class (with attachments),
  parents view them per child, submit assignments, teachers grade (marks + feedback), parents see
  the grade — full post → view → submit → grade loop (done)
- ✅ **Phase 9** — Reports & Analytics: reports center (student, admissions, fee collection,
  defaulters, branch summary) with **PDF (dompdf) + Excel/CSV + Print** export; enhanced analytics
  dashboard (8 KPIs incl. attendance %, new admissions; revenue-trend, class & branch charts) (done)
- ✅ **Phase 10** — Communication: SMS / WhatsApp / Email center with audience targeting
  (all parents, class parents, defaulters, staff, custom), real email delivery, complete
  communication logs, and one-click defaulter reminders (done)

**🎉 All 10 phases complete.**

### Additional modules
- ✅ **Student Portal** — dedicated student login (role-scoped to the one student): dashboard,
  attendance, results, homework + submit, fees, notices, profile
- ✅ **Transport** — routes + stops, vehicles & drivers, student route/stop assignment
- ✅ **Visitor Management** — check-in, printable visitor pass, check-out, daily history
- ✅ **Certificates** — editable templates (Character/Bonafide/Leaving/Experience/Custom) with
  `{{placeholders}}`, generate a filled PDF per student (wired into the Student 360° profile)
