# husseinfahmi/school-management-system architecture

> Architecture diagram of the GitHub repository husseinfahmi/school-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/husseinfahmi/school-management-system
- Repository: https://github.com/husseinfahmi/school-management-system

## Overview

#### 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: [`app/Modules/IAM/Actions/CreateUserAction.php`](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Actions/CreateUserAction.php) (IAM workflows), [`app/Modules/IAM/Controllers/Api/V1/AuthController.php`](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Controllers/Api/V1/AuthController.php) (Auth controller), [`app/Modules/IAM/Providers/IAMServiceProvider.php`](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Providers/IAMServiceProvider.php) (IAM composition), [`app/Http/Middleware/RequestIdMiddleware.php`](https://github.com/husseinfahmi/school-management-system/blob/main/app/Http/Middleware/RequestIdMiddleware.php) (Request ID middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Laravel Runtime"]
  node_public_index["HTTP bootstrap<br/>PHP entry point<br/>[index.php]"]
  node_artisan["CLI entry<br/>PHP CLI"]
  node_app_bootstrap["Application bootstrap<br/>Laravel bootstrap<br/>[app.php]"]
  node_providers["Provider registration<br/>Laravel providers<br/>[providers.php]"]
end

subgraph group_api["HTTP API"]
  node_iam_routes["IAM v1 routes<br/>API routes<br/>[v1.php]"]
  node_request_id["Request ID middleware<br/>HTTP middleware"]
  node_auth_controller["Auth controller<br/>API controller<br/>[AuthController.php]"]
  node_user_controller["User controller<br/>API controller<br/>[UserController.php]"]
  node_requests["Login and user requests<br/>form requests<br/>[LoginRequest.php]"]
end

subgraph group_iam["IAM Module"]
  node_iam_provider{{"IAM composition<br/>service provider"}}
  node_actions["IAM workflows<br/>application actions"]
  node_login_dto["Login DTO<br/>validated input<br/>[LoginDTO.php]"]
  node_auth_security["Authentication security<br/>security service"]
  node_token_service["Token service<br/>token lifecycle<br/>[TokenService.php]"]
  node_user_resource["User resource<br/>API resource<br/>[UserResource.php]"]
end

subgraph group_persistence["Persistence &amp; Audit"]
  node_user_repository["User repository boundary<br/>repository contract / Eloquent"]
  node_user_model["User model<br/>Eloquent model<br/>[User.php]"]
  node_iam_migrations[("IAM schemas<br/>database migrations")]
  node_events_listeners["IAM events and listeners<br/>domain event handlers<br/>[UserCreated.php]"]
  node_audit_log[("Audit log<br/>shared audit model<br/>[AuditLog.php]")]
  node_sanctum["Sanctum authentication<br/>token authentication config<br/>[sanctum.php]"]
end

node_public_index -->|"boots"| node_app_bootstrap
node_artisan -->|"boots"| node_app_bootstrap
node_app_bootstrap -->|"loads"| node_providers
node_providers -->|"registers"| node_iam_provider
node_iam_provider -->|"mounts"| node_iam_routes
node_iam_provider -->|"binds"| node_user_repository
node_iam_provider -->|"registers"| node_events_listeners
node_iam_routes -->|"middleware pipeline"| node_request_id
node_request_id -->|"login requests"| node_auth_controller
node_request_id -->|"user requests"| node_user_controller
node_auth_controller -->|"validates with"| node_requests
node_user_controller -->|"validates with"| node_requests
node_auth_controller -->|"maps input"| node_login_dto
node_auth_controller -->|"invokes login"| node_actions
node_user_controller -->|"invokes creation"| node_actions
node_actions -->|"enforces login controls"| node_auth_security
node_auth_security -->|"on successful auth"| node_token_service
node_token_service -->|"issues tokens via"| node_sanctum
node_actions -->|"persists through"| node_user_repository
node_user_repository -->|"Eloquent implementation"| node_user_model
node_user_model -->|"stored in IAM schema"| node_iam_migrations
node_actions -.->|"emits domain events"| node_events_listeners
node_events_listeners -->|"records audit history"| node_audit_log
node_actions -->|"returns shaped output"| node_user_resource

click node_public_index "https://github.com/husseinfahmi/school-management-system/blob/main/public/index.php"
click node_artisan "https://github.com/husseinfahmi/school-management-system/blob/main/artisan"
click node_app_bootstrap "https://github.com/husseinfahmi/school-management-system/blob/main/bootstrap/app.php"
click node_providers "https://github.com/husseinfahmi/school-management-system/blob/main/bootstrap/providers.php"
click node_iam_provider "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Providers/IAMServiceProvider.php"
click node_iam_routes "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Routes/v1.php"
click node_request_id "https://github.com/husseinfahmi/school-management-system/blob/main/app/Http/Middleware/RequestIdMiddleware.php"
click node_auth_controller "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Controllers/Api/V1/AuthController.php"
click node_user_controller "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Controllers/Api/V1/UserController.php"
click node_requests "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Requests/LoginRequest.php"
click node_actions "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Actions/CreateUserAction.php"
click node_login_dto "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/DTOs/LoginDTO.php"
click node_auth_security "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Services/AuthenticationSecurityService.php"
click node_token_service "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Services/TokenService.php"
click node_user_resource "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Resources/UserResource.php"
click node_user_repository "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Repositories/Contracts/UserRepositoryInterface.php"
click node_user_model "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Models/User.php"
click node_iam_migrations "https://github.com/husseinfahmi/school-management-system/tree/main/app/Modules/IAM/Database/Migrations"
click node_events_listeners "https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Events/UserCreated.php"
click node_audit_log "https://github.com/husseinfahmi/school-management-system/blob/main/app/Shared/Models/AuditLog.php"
click node_sanctum "https://github.com/husseinfahmi/school-management-system/blob/main/config/sanctum.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_index,node_artisan,node_app_bootstrap,node_providers toneBlue
class node_iam_routes,node_request_id,node_auth_controller,node_user_controller,node_requests toneAmber
class node_iam_provider,node_actions,node_login_dto,node_auth_security,node_token_service,node_user_resource toneMint
class node_user_repository,node_user_model,node_iam_migrations,node_events_listeners,node_audit_log,node_sanctum toneRose
```

## Components

### Laravel Runtime

- [HTTP bootstrap](https://github.com/husseinfahmi/school-management-system/blob/main/public/index.php): PHP entry point · `public/index.php`
- [CLI entry](https://github.com/husseinfahmi/school-management-system/blob/main/artisan): PHP CLI · `artisan`
- [Application bootstrap](https://github.com/husseinfahmi/school-management-system/blob/main/bootstrap/app.php): Laravel bootstrap · `bootstrap/app.php`
- [Provider registration](https://github.com/husseinfahmi/school-management-system/blob/main/bootstrap/providers.php): Laravel providers · `bootstrap/providers.php`

### HTTP API

- [IAM v1 routes](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Routes/v1.php): API routes · `app/Modules/IAM/Routes/v1.php`
- [Request ID middleware](https://github.com/husseinfahmi/school-management-system/blob/main/app/Http/Middleware/RequestIdMiddleware.php): HTTP middleware · `app/Http/Middleware/RequestIdMiddleware.php`
- [Auth controller](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Controllers/Api/V1/AuthController.php): API controller · `app/Modules/IAM/Controllers/Api/V1/AuthController.php`
- [User controller](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Controllers/Api/V1/UserController.php): API controller · `app/Modules/IAM/Controllers/Api/V1/UserController.php`
- [Login and user requests](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Requests/LoginRequest.php): form requests · Validate login and user-creation payloads. · `app/Modules/IAM/Requests/LoginRequest.php`

### IAM Module

- [IAM composition](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Providers/IAMServiceProvider.php): service provider · Registers IAM routes, bindings, and listeners. · `app/Modules/IAM/Providers/IAMServiceProvider.php`
- [IAM workflows](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Actions/CreateUserAction.php): application actions · Creates users and authenticates login requests. · `app/Modules/IAM/Actions/CreateUserAction.php`
- [Login DTO](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/DTOs/LoginDTO.php): validated input · `app/Modules/IAM/DTOs/LoginDTO.php`
- [Authentication security](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Services/AuthenticationSecurityService.php): security service · Applies failed-attempt and login security controls. · `app/Modules/IAM/Services/AuthenticationSecurityService.php`
- [Token service](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Services/TokenService.php): token lifecycle · `app/Modules/IAM/Services/TokenService.php`
- [User resource](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Resources/UserResource.php): API resource · `app/Modules/IAM/Resources/UserResource.php`

### Persistence & Audit

- [User repository boundary](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Repositories/Contracts/UserRepositoryInterface.php): repository contract / Eloquent · Domain persistence is accessed through a replaceable contract. · `app/Modules/IAM/Repositories/Contracts/UserRepositoryInterface.php`
- [User model](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Models/User.php): Eloquent model · `app/Modules/IAM/Models/User.php`
- [IAM schemas](https://github.com/husseinfahmi/school-management-system/tree/main/app/Modules/IAM/Database/Migrations): database migrations · Owns user, permission, session, security-history, reset-token, and token schemas. · `app/Modules/IAM/Database/Migrations`
- [IAM events and listeners](https://github.com/husseinfahmi/school-management-system/blob/main/app/Modules/IAM/Events/UserCreated.php): domain event handlers · Records creation audits, password history, and login history asynchronously from workflows. · `app/Modules/IAM/Events/UserCreated.php`
- [Audit log](https://github.com/husseinfahmi/school-management-system/blob/main/app/Shared/Models/AuditLog.php): shared audit model · `app/Shared/Models/AuditLog.php`
- [Sanctum authentication](https://github.com/husseinfahmi/school-management-system/blob/main/config/sanctum.php): token authentication config · Provides personal-access-token API authentication. · `config/sanctum.php`

## Connections

- 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