StaffPass

What It Is

StaffPass is a Laravel-based web application designed to help schools manage staff and student movements across multiple campuses. It centralizes class lists, site roles, and permission assignments so administrators can issue movement passes and track activity. Target users are school administrators and staff – office administrators who manage roles and classes, teachers who issue student passes, and IT personnel who integrate the system with identity providers.

A React frontend provides a user-friendly interface for day-to-day interactions, while the Laravel backend exposes a REST API consumed by the web UI and third-party integrations. This mix of a modern SPA frontend with a robust backend offers a seamless experience for end users and a stable platform for developers.

Version History

StaffPass has gone through two major versions:

Version 1: MC Password Management (jQuery/Bootstrap)

The original version was built with jQuery, Bootstrap, and pure HTML/CSS. It was a simpler implementation focused on password management and basic student/staff lookup functionality.

The original password management interface showing the class list with reset functionality

Search interface for finding students in the database

Search results showing student details with role information

Action sidebar with email options (parent, self, student), export, reset, and edit functions

Generated PDF welcome letter with student credentials and helpful links

Role-based permissions editor allowing granular control over features like password reset, email functions, and PDF export

V1 Repository: github.com/45ck/staffpass

Version 2: StaffPass Laravel (Current)

The complete rewrite in Laravel and React addressed the limitations of V1:

• SAML SSO replaced basic authentication
• Role-based access control with site-scoped permissions
• Movement pass system for tracking student locations
• Comprehensive audit logging for compliance
• Containerized deployment with Docker
• 80%+ test coverage with automated CI/CD

Problem & Constraints

Problem: Schools with multiple sites traditionally struggled to coordinate staff access and student movements, often relying on inconsistent spreadsheets and manual processes. StaffPass was created to provide a unified system to assign roles per site, maintain class rosters, and issue temporary passes to students. Teachers can quickly issue a hall pass and see which students are out of class, and administrators can run attendance and pass-usage reports centrally. Audit logging is built in to provide accountability for every action.

Key Constraints

• Data Privacy & Compliance: Strict data privacy and policy requirements. Strong security controls and compliance with data retention rules (one-year log retention and encrypted storage of sensitive fields).
• Integration with Existing Infrastructure: Schools already used Azure Active Directory for single sign-on, requiring SAML SSO authentication rather than local passwords.
• Multi-Site Scale: Multiple campuses with potentially thousands of students and staff. This influenced design decisions like using UUID identifiers and a normalized data model.
• Time & Resource Constraints: Leveraging frameworks (Laravel) and open-source packages (for auditing, SAML, etc.) to avoid reinventing the wheel.
• Operational Continuity: Minimal downtime and robust disaster recovery (nightly database backups and regular restore testing).

My Role

I served as the lead developer and architect, driving both implementation and technical design:

• Implemented SAML2 single sign-on integration with Azure AD
• Set up role management features and end-to-end tests
• Designed the data model (persons, roles, sites, etc.)
• Developed core features: pass issuance, auditing logic
• Wrote extensive documentation and runbooks
• Established CI/CD pipeline and quality gates (GitHub Actions, Docker, security scans)
• Collaborated with architecture review board for design approval

Outcome & Impact

StaffPass delivered significant improvements in managing campus access:

• Manual effort reduced: Tasks that used spreadsheets and paper forms now handled in a few clicks. Bulk password resets and standardized welcome letters for new students.
• Centralized data: Eliminated inconsistencies and duplication across all sites.
• Faster processing: Pass issuance went from minutes with paper logs down to seconds via the app.
• 100% audited: Every access event is now audited and searchable (versus virtually none before).
• 99.9% uptime in first year.
• Passed rigorous security audit aligning with OWASP and NIST best practices.
• Developer onboarding: Comprehensive documentation and test suite enabled onboarding new developers in days instead of weeks.

Architecture

StaffPass employs a client–server architecture with clear separation between frontend and backend.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   React SPA     │────▶│   Laravel API   │────▶│   SQL Server    │
│   (Frontend)    │     │   (PHP-FPM)     │     │   (Database)    │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        │                        │                        │
        ▼                        ▼                        ▼
┌───────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   Azure AD    │      │     Nginx       │      │     Docker      │
│   (SAML SSO)  │      │   (Reverse Proxy)│      │   Containers    │
└───────────────┘      └─────────────────┘      └─────────────────┘

Backend Structure

The Laravel backend follows a standard layered structure:

• app/Http/ - Controllers and middleware
• app/Services/ - Domain services implementing business logic
• app/Models/ - Eloquent ORM models
• config/ - Configuration files
• routes/ - API routes and web routes for SAML login

Key Components & Boundaries

• Laravel API server - Business logic and data access
• React client - User interface
• SQL database - System of record (SQL Server in production, SQLite in development)
• Azure AD - External identity provider (SAML)

In production, these run as Docker containers behind Nginx acting as a reverse proxy. The React frontend communicates with the Laravel API over HTTPS using JSON.

Core Technical Decisions

Laravel Monolith + React SPA vs. Microservices

Chose Laravel for rapid development (out-of-the-box routing, ORM, security) and React for responsive, modern interface (dynamic tables, immediate form validation). Ruled out microservices due to project scope and timeline – a single Laravel application was sufficient and far quicker to maintain.

Containerized Environment

Fully containerized using Docker Compose for development and deployment:

• Laravel app (PHP-FPM)
• Node service for asset building
• Nginx webserver

This ensures consistent environments across developers’ machines and CI, eliminating “works on my machine” issues.

SAML SSO vs. Local Auth

Integrated with Azure AD using SAML 2.0 for single sign-on. School staff and students already had accounts in institutional AD, and SSO provides seamless and secure login. On login, user is redirected to Azure AD; upon successful authentication, Laravel receives a SAML assertion and issues a JWT for API calls. This makes the app stateless and scalable.

Role-Based Access Control & Auditing

Used flexible RBAC schema with Role and Permission entities. Permissions can be site-scoped (teacher at Campus A shouldn’t see data for Campus B). Integrated Laravel auditing package (OwenIt\Auditing) to automatically record create/update/delete events. Audit records pruned after 1 year to control growth.

Quality & Security Tooling in CI

Embedded static analysis and security scans into development workflow:

• PHPStan (strict static analysis for PHP)
• Semgrep (custom security rule scanning)
• ESLint for JS
• Gitleaks (secret scanning)
• OWASP ZAP scan against deployed test instance

Security workflow runs on each push/PR and scheduled monthly scan.

Infrastructure & Deployment

Production Stack

• Docker containers (Laravel PHP-FPM, Node, Nginx)
• Azure SQL database (SQL Server)
• Environment-specific configuration via .env and secrets manager

CI/CD Pipeline (GitHub Actions)

1. On every push/PR:

   • Install PHP and Node dependencies
   • Run PHPUnit test suite for backend
   • Run Jest/Playwright tests for frontend
   • Perform security audits (composer audit, npm audit)

2. On success:

   • Build Docker image from PHP 8.2 base
   • Compile React assets (npm run prod)
   • Run migrations (php artisan migrate —force)
   • Push versioned Docker images

Deployment Process

1. Merge PR to main → CI builds new Docker image
2. Deploy to staging → pull image, update containers, run migrations
3. Smoke tests on staging (Playwright E2E + manual verification)
4. Promote to production → same image, run migrations
5. Rollback plan: Redeploy previous Docker image + php artisan migrate:rollback

Nightly Jobs

• Rebuild and scan container for security updates
• Base images stay up to date with patches (DevSecOps practice)

Data Model

Relational schema centered around People, their roles, and organizational structure.

Key Entities

Person (base identity)
  ├── Staff (job title, site assignments)
  │     └── StaffRole (staff_id, role_id, site_id)
  └── Student (year, class group)
        └── Class (site_id, name)

Site (campus/location)
Role ←→ Permission (many-to-many)
Audit (change logs for compliance)

Design Decisions

• UUID primary keys for global uniqueness across sites
• Separate Person table for core identity (avoids duplication between Staff/Student)
• Composite key pivot (StaffRole) for site-scoped role assignments
• Foreign key constraints for referential integrity
• JSON columns for flexible data where needed

Migration Strategy

Laravel’s migration system with timestamped files. Running php artisan migrate applies new migrations in order. Rollback with php artisan migrate:rollback. Nightly backups provide safety net.

Security

Authentication & Session Security

• All authentication via Azure AD (SAML 2.0)
• JWT tokens for API sessions
• EncryptCookies middleware encrypts session cookies
• HTTP-only and Secure flags on cookies
• Idle timeout and logout mechanism

Authorization

• Custom RoleMiddleware checks JWT user identity
• Loads roles and permissions, verifies required permission
• Multi-tenant isolation: user’s role assignment must match site/resource
• All rules tested with unit and integration tests

Data Protection

• All traffic encrypted via HTTPS/TLS
• PII fields (names, emails) encrypted at rest using Laravel’s AES-256-GCM
• Passwords hashed using bcrypt
• Annual key rotation with documented runbook
• Audit logs never include raw PII
• Backups encrypted and stored off-site

Operational Security

CI pipeline security workflow:

• Semgrep (encryption usage, no hardcoded secrets)
• Gitleaks (detect committed secrets)
• Dependency audits (composer audit, npm audit, pip-audit)
• OWASP ZAP baseline passive scan
• Results uploaded as artifact, CI fails on high/medium issues

Security Operations Guide for incident response: revoke JWT tokens, rotate keys, restore from backup.

Reliability & Observability

Logging

• Laravel log on daily rotation (365 days retention)
• INFO level in production (logins, pass issuance, errors)
• Sanitized logs (no PII, only IDs)
• Fluent Bit agents aggregate container logs to central logging system

Monitoring Metrics (Prometheus + Grafana)

• CPU and memory usage
• Request throughput and response time
• Error rate
• Database query time
• Background queue length
• Request latency p95, active JWT sessions, DB connections

Alerting

• Error rate >1% for 5 minutes → alert
• Queue depth >100 (warning), >500 (critical)
• CPU >85% sustained → alert
• Minor alerts to Slack, critical alerts page on-call via PagerDuty
• Alertmanager with 15-minute escalation policy

Backup & Recovery

• Nightly database backups (mysqldump equivalent)
• Automatic transfer to off-site storage (Azure Blob with encryption)
• Monthly restore tests with verification
• Documented procedures for production restore

Testing Strategy

Automated Test Suite

Backend (PHPUnit):

• Unit tests: individual classes/functions (e.g., RoleService permission aggregation)
• Feature tests: HTTP requests against test instance (API auth flows, permission enforcement)

Frontend:

• Jest for unit tests of React components and utilities
• Playwright for E2E browser tests

Test Coverage

• 80% code coverage target for backend
• Critical classes (RoleMiddleware, AuthenticationController) near 100%
• Coverage tracked in QUALITY_PLAN.md

CI and Pre-Commit

• Git pre-commit hook runs PHPUnit and frontend tests
• PHPStan (level max with security rules)
• ESLint for JS style
• Linter warnings treated as errors

Regression Testing

• Bug fix accompanied by new regression test
• Philosophy: “if a bug is found, first write a test that reproduces it, then fix”
• Multi-layered approach: pre-commit hooks, CI enforcement, broad coverage, E2E tests

End-to-End Testing

• Playwright scripts for critical user journeys
• Different user roles (teacher vs admin)
• Application in test mode with SQLite and seeded users
• Manual QA phase for each release with documented test plan

Performance

Architecture Scalability

• Stateless API with JWTs and single database
• Horizontal scaling: add Laravel servers behind load balancer
• Single VM (2 vCPU, 4 GB RAM) handles few hundred concurrent users
• Can support 5-10x initial user count

Database Performance

• Appropriate indexes on foreign keys
• Composite indexes for common query patterns
• Eager loading to avoid N+1 queries
• Caching for reference data (permissions, roles)
• P95 response time ~150ms

Benchmarking Results

• 50 concurrent teachers issuing passes: average response <200ms
• Bulk password reset (30 students): <2 seconds
• Export 2000 student records to CSV: ~1.5 seconds

Frontend Performance

• Production React build (minified)
• Code-splitting for heavy admin pages
• Gzip compression
• App loads within 2-3 seconds on typical school network

UX & Accessibility

Key UX Design Choices

• Standard web app layout: sidebar navigation, main content area
• Quick search and filtering on all tables
• Bulk operations (password resets, exports)
• Sidebar forms for editing (no page navigation)
• Confirmation modals for destructive actions
• Site filter dropdown for multi-campus context switching
• Audit log viewer with formatted JSON diffs

Accessibility (WCAG Compliance)

• ARIA attributes and roles on interactive components
• Sufficient color contrast
• Full keyboard navigation (Tab/Shift+Tab)
• Visible focus indicators
• aria-live on toast notifications
• Form error messages linked to fields
• Tested with NVDA screen reader

Responsive Design

• Bootstrap grid layout
• Sidebar becomes top nav on narrow screens
• Scrollable tables
• Works on tablets and phones

Future Enhancements

• Mobile/PWA: Dedicated mobile app for hall monitors
• Real-Time Updates: WebSockets/Laravel Echo for live pass notifications
• Hardware Integration: QR code scanning for student IDs
• Enhanced Analytics: Trends, heatmaps, predictive alerts
• Performance at Scale: Redis caching, Laravel Horizon job queue
• Multi-Tenancy: Tenant-level data silos for multiple districts
• Security Hardening: MFA enforcement, Content Security Policy, RASP integration