How husseinfahmi/school-management-system works
Purpose and runtime
This is a Laravel/PHP backend for a School Management System, currently centered on an Identity and Access Management (IAM) module. It exposes versioned HTTP APIs rather than a browser application. PHP/Laravel bootstraps through public/index.php and CLI operations through artisan; application setup is defined in bootstrap/app.php.
HTTP API entry and request boundary
IAM routes are mounted from app/Modules/IAM/Routes/v1.php and handled by app/Modules/IAM/Controllers/Api/V1/AuthController.php and app/Modules/IAM/Controllers/Api/V1/UserController.php. Requests pass through Laravel’s middleware pipeline, including correlation/request-ID handling in app/Http/Middleware/RequestIdMiddleware.php. Form-request classes validate inbound payloads before controller/action execution:
app/Modules/IAM/Requests/LoginRequest.php and app/Modules/IAM/Requests/StoreUserRequest.php.
Modular IAM domain
app/Modules/IAM is a self-contained vertical module: API controllers orchestrate use cases, actions hold application workflows, DTOs carry validated inputs, and resources shape outputs. The current principal workflows are user creation and authentication:
app/Modules/IAM/Actions/CreateUserAction.php,
app/Modules/IAM/Actions/LoginAction.php,
app/Modules/IAM/Resources/UserResource.php.
Authentication and security flow
Login input is converted into app/Modules/IAM/DTOs/LoginDTO.php, processed by LoginAction, and governed by app/Modules/IAM/Services/AuthenticationSecurityService.php for security controls such as failed-attempt handling. Successful authentication delegates token lifecycle concerns to app/Modules/IAM/Services/TokenService.php. Laravel Sanctum is configured at config/sanctum.php, indicating personal-access-token-based API authentication; the corresponding token schema is in app/Modules/IAM/Database/Migrations/2026_07_31_194927_create_personal_access_tokens_table.php.
Persistence and repository boundary
Domain code accesses user and login-history persistence through contracts, allowing Eloquent implementations to remain replaceable:
app/Modules/IAM/Repositories/Contracts/UserRepositoryInterface.php,
app/Modules/IAM/Repositories/Eloquent/UserRepository.php,
app/Modules/IAM/Models/User.php.
IAM owns migrations for users, permissions, sessions, audit/security history, and reset tokens under app/Modules/IAM/Database/Migrations. Database connection and cache/queue infrastructure are Laravel-configured in config/database.php, config/cache.php, and config/queue.php.
Event-driven audit and history side effects
Core actions emit domain events so audit/history work is decoupled from synchronous workflows. User creation raises app/Modules/IAM/Events/UserCreated.php, consumed by listeners such as app/Modules/IAM/Listeners/LogUserCreationAudit.php and app/Modules/IAM/Listeners/RecordInitialPasswordHistory.php. Login processing raises app/Modules/IAM/Events/LoginAttempted.php, with history recorded by app/Modules/IAM/Listeners/RecordLoginHistory.php. Cross-module audit records are represented by app/Shared/Models/AuditLog.php.
Composition and external packages
app/Modules/IAM/Providers/IAMServiceProvider.php is the module’s composition boundary, expected to register routes, bindings, and event listeners. Root providers are registered via bootstrap/providers.php. The repository uses Laravel’s service ecosystem and configurations for authentication, mail, filesystem storage, logging, cache, queues, Sanctum, permissions, activity logging, and API documentation (config/auth.php, config/mail.php, config/scramble.php).
Main entry points: CreateUserAction.php IAM workflows · AuthController.php Auth controller · IAMServiceProvider.php IAM composition · RequestIdMiddleware.php Request ID middleware
Components 21
Laravel Runtime
- HTTP bootstrap
public/index.php - CLI entry
artisan - Application bootstrap
bootstrap/app.php - Provider registration
bootstrap/providers.php
HTTP API
- IAM v1 routes
app/Modules/IAM/Routes/v1.php - Request ID middleware
app/Http/Middleware/RequestIdMiddleware.php - Auth controller
app/Modules/IAM/Controllers/Api/V1/AuthController.php - User controller
app/Modules/IAM/Controllers/Api/V1/UserController.php - Login and user requests · Validate login and user-creation payloads.
app/Modules/IAM/Requests/LoginRequest.php
IAM Module
- IAM composition · Registers IAM routes, bindings, and listeners.
app/Modules/IAM/Providers/IAMServiceProvider.php - IAM workflows · Creates users and authenticates login requests.
app/Modules/IAM/Actions/CreateUserAction.php - Login DTO
app/Modules/IAM/DTOs/LoginDTO.php - Authentication security · Applies failed-attempt and login security controls.
app/Modules/IAM/Services/AuthenticationSecurityService.php - Token service
app/Modules/IAM/Services/TokenService.php - User resource
app/Modules/IAM/Resources/UserResource.php
Persistence & Audit
- User repository boundary · Domain persistence is accessed through a replaceable contract.
app/Modules/IAM/Repositories/Contracts/UserRepositoryInterface.php - User model
app/Modules/IAM/Models/User.php - IAM schemas · Owns user, permission, session, security-history, reset-token, and token schemas.
app/Modules/IAM/Database/Migrations - IAM events and listeners · Records creation audits, password history, and login history asynchronously from workflows.
app/Modules/IAM/Events/UserCreated.php - Audit log
app/Shared/Models/AuditLog.php - Sanctum authentication · Provides personal-access-token API authentication.
config/sanctum.php
Connections 24
- HTTP bootstrap → Application bootstrap: boots
- CLI entry → Application bootstrap: boots
- Application bootstrap → Provider registration: loads
- Provider registration → IAM composition: registers
- IAM composition → IAM v1 routes: mounts
- IAM composition → User repository boundary: binds
- IAM composition → IAM events and listeners: registers
- IAM v1 routes → Request ID middleware: middleware pipeline
- Request ID middleware → Auth controller: login requests
- Request ID middleware → User controller: user requests
- Auth controller → Login and user requests: validates with
- User controller → Login and user requests: validates with
- Auth controller → Login DTO: maps input
- Auth controller → IAM workflows: invokes login
- User controller → IAM workflows: invokes creation
- IAM workflows → Authentication security: enforces login controls
- Authentication security → Token service: on successful auth
- Token service → Sanctum authentication: issues tokens via
- IAM workflows → User repository boundary: persists through
- User repository boundary → User model: Eloquent implementation
- User model → IAM schemas: stored in IAM schema
- IAM workflows → IAM events and listeners: emits domain events
- IAM events and listeners → Audit log: records audit history
- IAM workflows → User resource: returns shaped output