Overview

ProductSchool is an enterprise-grade school management system (Sistem Informasi Manajemen Sekolah) built to centralize every operational workflow of an Indonesian K-12 school into a single platform. Running in production at SD Muhammadiyah 3 Samarinda since 2024, it serves approximately 480 students across 42 classrooms and 100+ employees — handling academic management, automated report cards, financial processing, payroll, GPS-based attendance, WhatsApp communication with AI-powered chatbot, and real-time operations.

This project represents the most technically complex system I have engineered end-to-end: 132 Eloquent models, 146 controllers, 111 service classes, 893 routes, 18 distinct user roles with 272 granular permissions, and integrations with 8 external services. The codebase has been developed over 58+ intensive sessions with continuous production deployment.

Quantified Results

- 893 routes (708 web + 185 API) serving dashboard, mobile apps, WhatsApp bot, and public landing simultaneously - 132 models, 146 controllers, 111 services — service-oriented architecture with domain-driven module separation - 18 user roles with 272 permissions via Spatie Laravel Permission, with data-level scoping per teacher and per parent - 157+ test files with 1,233 test methods and ~3,000 assertions, running in parallel via CI - 24 artisan console commands for automation, monitoring, and operational workflows - 27 broadcast events and 21 listeners powering real-time WebSocket updates across 12 channels - 16 AI tools for the WhatsApp bot with function-calling, NLP intent detection, and OCR document analysis - Headless Chrome PDF generation for report cards with QR verification, digital signatures, and batch processing - Midtrans payment gateway with Virtual Account, QRIS, webhook reconciliation, and automated billing - 43 mobile API endpoints for the parent application with Sanctum authentication

Architecture

Service-Oriented Monolith

Rather than distributing across microservices, I organized the system as a service-oriented monolith — 111 dedicated service classes handle business logic while controllers remain thin route handlers. Each of the 52 production modules has its own controller, service, form requests, policies, and events. This approach gave us the operational simplicity of a single deployment while maintaining clean domain boundaries.

The architecture follows a consistent pattern across all modules: Routes → Middleware (permission strings) → Controller → Form Request validation → Service → Model → Policy. Form Requests isolate validation per action. Services encapsulate business rules. Policies enforce authorization at the model level. Events and listeners decouple side effects (notifications, broadcasts, audit logging).

Data-Level Security (RBAC + Scoping)

The permission system operates at three layers:

1. Route middleware — 277 unique permission strings check access before controller execution 2. Model policies — 34 policies enforce authorization at the data level (e.g., PaymentPolicy checks view-payments permission, not role names) 3. Query scoping — TeacherScopedData trait restricts database queries to only the classrooms, students, and subjects assigned to each teacher. Parents see only their own children's data via getParentStudentIds().

The FULLSCOPEROLES constant defines roles that bypass teacher-level scoping (kepalasekolah, keuangan, tenagapendidikan, gurubk) while still respecting parent-level scoping. This three-layer approach means a teacher literally cannot query data outside their assigned classrooms — the restriction exists at the database level, not just the UI.

Real-Time Architecture

Laravel Reverb (Pusher-compatible WebSocket server) broadcasts events across 12 channels:

- whatsapp-conversations — live chat sidebar and message delivery - payment-updates — payment completion triggers matrix refresh - attendance-updates — check-in/check-out reflected immediately - grade-updates — grade entry triggers live index refresh - data-updated — generic channel for DataTable auto-refresh across transfer, graduation, retention, and promotion workflows

The frontend implements a smart client architecture: WebSocket connection when available, polling fallback with !window.Echo guard to prevent duplicate requests, exponential backoff reconnection, and activity-based timeout (30s idle disconnect).

Core Features

AI-Powered WhatsApp Bot

The most technically distinctive feature — parents can retrieve verified school information by chatting the school's WhatsApp number. No app installation required.

How it works: - Meta WhatsApp Cloud API receives incoming messages via webhook (HMAC-SHA256 verified) - NLP pipeline processes intent: menu number selection → NISN lookup → keyword matching → fuzzy/levenshtein scoring → abbreviation expansion → composite intent detection → negation penalty - Ollama LLM (qwen2.5:3b, running locally) performs function-calling with 16 read-only tools against verified school data - Bot cannot fabricate numbers — it must call tools; results are formatted for WhatsApp delivery

16 AI tools: getstudentpayments, getstudentattendance, getstudentgrades, getstudentschedule, getstudentprofile, getstudentsummary, getstudentextracurriculars, getwalikelas, getschoolinfo, getacademiccalendar, getschoolnews, getregistrationinfo, getpaymentmethods, getleaveinstructions, and more.

Conversation state machine: IDLE → AWAITINGSTUDENTID → AWAITINGSTUDENTSELECTION → IDLE (verified) with branches for leave requests, payment confirmation, and human handoff. Students verified via NISN (10-digit) + phone match. 3 failed attempts → blocked. Multiple children → selection dialog.

OCR integration: Parents can photograph payment receipts or sick letters. Tesseract OCR extracts text, LLM validates the document, and verified information is recorded automatically. OCR names are scoped to the verified parent's own children to prevent misattribution.

Human handoff: When confidence is low or the parent is urgent/complaining, the conversation escalates to admin staff. When an admin replies from the dashboard, the bot auto-holds — a single acknowledgment message is sent, then the bot stays silent until the parent returns to the menu.

Automated Report Cards (Rapor)

Visual template builder: Canvas-based drag-and-drop section editor (React 19 + react-konva) with 16 section types: student info, grade tables, descriptions, P5 assessment, inclusion (ABK), signatures, and more. Templates support page breaks, custom paper sizes, fonts, school letterhead, watermarks, and QR codes.

PDF generation pipeline:

Each student's rapor is dispatched as an individual job via Laravel Queue with Bus::batch for progress tracking. The entire pipeline renders variable expressions ({{=round(gradescore * 100) / 100}} via Symfony ExpressionLanguage), resolves dynamic data sources (grades, attendance, extracurriculars, P5, inclusion), and generates print-quality PDFs.

Verification: Public /verify/{code} endpoint displays the rapor + PDF when scanned via QR code. Rate-limited to 120 requests/minute.

Payment & Financial System

Midtrans integration handles Virtual Account and QRIS payments. The system includes: - Automatic monthly bill generation (configurable via scheduler) - Webhook-driven status synchronization with SHA-512 signature verification - Payment reconciliation job running every 6 hours (queries Midtrans API for pending charges ≥24 hours old) - Anti-downgrade guard: prevents webhook from reverting a completed payment to pending - Anti-duplicate bill creation: DB::transaction + lockForUpdate on PaymentTitle as mutex

Payment matrix view: Admin sees a student × month grid with bulk edit capabilities — mark paid, send reminders, or delete. WhatsApp reminders use H-3/H-1/H+1 cadence with once-per-day throttling.

GPS Geofencing Attendance

Employee attendance uses device-based check-in with KML polygon geofencing: - Polygon boundaries defined via Google Earth KML files uploaded to the system - Check-in validated against polygon (point-in-polygon algorithm) - National holiday API sync (SKB 3 Menteri) — holidays are not scored as absent - Role-based work hours (RoleWorkHour) with configurable check-in deadlines - Late penalties and early arrival incentives per role - Auto-alpha job at 16:00 WIB marks absent employees (skips holidays, approved leave, non-working shifts) - Prayer attendance tracking (Dhuha/Dzuhur) with separate geofence zone

Payroll & HR

- Monthly payroll processing with salary components (base salary, tenure, functional, structural, education, allowances, deductions, bonus) - Attendance-based calculations using published attendance records - Anti-negative salary: clampFinalSalary() applied at preparation and processing stages - PDF salary slips with employee digital signatures (draw/upload fallback) - Bulk Excel export and ZIP download - Self-service "My Payroll" portal for employees - Role-based access: only keuangan, Penggajian, and superadmin can process payroll

Mobile API (Parent & Teacher)

43 parent endpoints covering: authentication (OTP login), dashboard, children list, profile, bills + Midtrans Snap token payment, grades + transcripts, attendance summaries, rapor PDF streaming, extracurriculars, push notifications (FCM), and news. All data scoped to verified parent-child relationships.

9 teacher endpoints covering: class roster, bulk attendance, my-attendance with geofence, check-in/out, and prayer attendance.

REST API architecture: Laravel Sanctum token authentication, standardized JSON envelope ({success, message, data, meta, links}), audit logging on all sensitive endpoints via LogSensitiveRequests middleware, and explicit numeric formatting ((float), ISO8601 dates).

CMS & Multi-Channel Publishing

Article management with Quill editor, cover photos, multi-image galleries, and document attachments. Publish simultaneously to: - Website (filtered for parent API) - Instagram (carousel via Instagram Graph API, max 10 images) - Facebook (Page feed via Graph API) - WhatsApp (broadcast template to targeted classrooms) - Push notifications (FCM to parent devices)

Technical Architecture

Backend

- Laravel 12 with PHP 8.3+, MySQL 8, Redis 7 - Laravel Reverb for WebSocket (Supervisor-managed) - Laravel Sanctum for API token authentication - Laravel Queue with database driver (batch jobs for rapor, imports) - Laravel Scheduler for cron-based automation - Spatie Laravel Permission for RBAC - Headless Chrome (Browsershot) for print-quality PDF rendering - Tesseract OCR for document analysis - Ollama (qwen2.5:3b) for AI function-calling

Frontend

- Blade Components with Bootstrap 5 and Tailwind CSS - React 19 + react-konva 19 + Zustand for the Canvas document template editor - Yajra Laravel DataTables for server-side paginated data tables - SweetAlert2 for confirmations and notifications - Chart.js / ApexCharts for dashboard visualizations - GSAP animations for landing page

Integrations

- Meta WhatsApp Cloud API — two-way chat, templates, media, OCR - Meta Graph API — Facebook page publishing - Instagram Graph API — carousel publishing - Midtrans — Virtual Account, QRIS, Snap UI, webhook reconciliation - Ollama — local LLM for AI chatbot - Tesseract — OCR for payment receipts and sick letters - Firebase Cloud Messaging — push notifications to mobile - Twilio — OTP SMS (optional) - National Holiday API — SKB 3 Menteri sync

Infrastructure

- Nginx + PHP-FPM 8.3 serving - Cloudflare CDN and WAF - GitHub Actions CI/CD (Pint + PHPStan + Paratest + build) - Supervisor for queue workers and Reverb - MySQL 8 production, SQLite in-memory for tests

Security

18 user roles with 272 granular permissions, managed via Spatie Laravel Permission:

| Role | Description | |---|---| | superadmin | System owner, bypasses all checks (270 permissions) | | adminsekolah | Full admin access to all modules (241 permissions) | | adminakademik | Curriculum and academic administration (127 permissions) | | kepalasekolah | Headmaster — view-heavy with approval authority (61 permissions) | | guru / walikelas | Teacher / homeroom teacher (67 permissions) | | gurumapel | Subject teacher — grade input only (35 permissions) | | gurubk | Guidance counselor (36 permissions) | | keuangan / Penggajian | Finance / payroll (58/23 permissions) | | kepegawaian | HRD (53 permissions) | | orang_tua | Parent — mobile app, own children only (12 permissions) | | siswa | Student — limited view (6 permissions) |

Defense-in-depth layers: 1. Route middleware with 277 unique permission strings 2. 34 model policies enforcing authorization at the data level 3. TeacherScopedData trait restricting queries at the database level 4. Parent-scoped access via getParentStudentIds() 5. Audit logging on all critical actions (IP, user agent, old/new values) 6. CSRF protection, HMAC webhook verification (Midtrans SHA-512, WhatsApp/Instagram HMAC) 7. Nginx security headers: CSP (no unsafe-eval), HSTS, Referrer-Policy, COOP/CORP 8. Rate limiting on API endpoints, OTP, and webhook ingestion

Engineering Decisions

Service-Oriented Monolith over Microservices — With 52 interconnected modules sharing database transactions and domain models, microservices would have introduced distributed transaction complexity without proportional benefit. The service-oriented monolith gives us domain isolation via 111 service classes while maintaining ACID guarantees across modules like payments, payroll, and attendance.

Ollama (Local LLM) over Cloud AI — Running qwen2.5:3b locally via Ollama eliminates API costs, removes external dependency for the WhatsApp bot, and keeps student data on-premise. The OpenAI-compatible tool-calling interface made function-calling integration straightforward. Fallback to plain chat ensures parents always get a response even if the LLM is under load.

Headless Chrome over DomPDF for Rapor — Report cards require print-quality rendering with complex layouts, QR codes, digital signatures with transparency, and school letterhead watermarks. DomPDF's CSS support limitations made it unsuitable for the visual template builder's output. Browsershot (headless Chrome) renders the exact same HTML/CSS the template builder produces, ensuring WYSIWYG fidelity.

Data-Level Scoping over UI-Level Filtering — The TeacherScopedData trait applies WHERE clauses at the Eloquent query level rather than filtering results after retrieval. This means a teacher accessing the system through the API, dashboard, WhatsApp bot, or any other interface gets the same data restrictions. The scoping cannot be bypassed by manipulating frontend controls.

Queue-Based Batch Processing for Rapor — Generating 480+ report cards synchronously would timeout any HTTP request. Each rapor is dispatched as an individual queued job within a Bus::batch, enabling parallel processing with real-time progress tracking. The batch system handles job failures gracefully — a single student's rapor failure doesn't block the rest.

Engineering Impact

ProductSchool demonstrates that a monolithic Laravel application, when organized with service classes, data-level scoping, and domain-driven module boundaries, can handle enterprise-level complexity across 52 interconnected modules. The system processes thousands of daily operations — attendance check-ins, payment transactions, grade entries, WhatsApp conversations, rapor generation — without architectural compromises.

The AI-powered WhatsApp bot shows how local LLMs can be production-ready for domain-specific tasks when combined with function-calling and proper data access controls. Parents interact with verified school data through natural language without installing an app or learning a new interface.

The data-level RBAC implementation (18 roles, 272 permissions, query-level scoping) demonstrates how backend engineering decisions directly impact security posture — authorization is enforced uniformly regardless of access path (web, API, bot, mobile).

Technologies Used

Backend Laravel 12, PHP 8.3+, MySQL 8, Redis 7, Laravel Reverb, Laravel Sanctum, Spatie Laravel Permission, Laravel Queue, Laravel Scheduler, Browsershot (Headless Chrome), Tesseract OCR, Ollama (qwen2.5:3b)

Frontend Blade Components, Bootstrap 5, Tailwind CSS, React 19 + react-konva 19 (Canvas editor), Yajra DataTables, Chart.js, SweetAlert2, GSAP

Integrations Midtrans Payment Gateway (VA/QRIS), Meta WhatsApp Cloud API, Meta Graph API (Facebook), Instagram Graph API, Firebase Cloud Messaging, Ollama AI, Tesseract OCR, Twilio (optional)

Infrastructure Nginx + PHP-FPM 8.3, MySQL 8, Redis 7, Cloudflare CDN/WAF, GitHub Actions CI/CD, Supervisor