Backend - Laravel

Purpose

This page documents the backend layer of the Maqsafy platform, including the Laravel application structure, responsibilities, API behavior, background jobs, logs, and operational rules.

Backend Responsibilities

The backend is responsible for:

• Business logic
• API endpoints
• Authentication and authorization
• Role-based access control
• Wallet and transaction handling
• Orders and refunds
• School, student, and cafeteria operations
• Supplier and operator workflows
• Reports and exports
• Background jobs
• Integration with external services

Core Modules

Module	Description
Authentication	Login, logout, token validation, password reset, OTP where applicable
RBAC	Role and permission enforcement
Schools	School profile, branches, cafeterias, and operational settings
Students	Student records, roster import, status management
Products	Product catalog, availability, and pricing
Orders	Order creation, order tracking, and order history
Wallet	Wallet balance, transactions, refunds, and ledger records
Procurement	Purchase orders, supplier fulfillment, receiving, and invoices
Credentials	Card / bracelet inventory, assignment, delivery, and lifecycle events
Reports	Sales, settlement, operational, and audit reports
Support	Tickets, messages, attachments, and communication records

API Structure

API routes should be organized by domain and protected by the required middleware.

Example route groups:

Route::prefix('api')->group(function () {
    Route::post('/login', [AuthController::class, 'login']);

    Route::middleware(['auth:sanctum'])->group(function () {
        Route::get('/profile', [ProfileController::class, 'show']);

        Route::prefix('admin')->middleware(['role:admin'])->group(function () {
            Route::apiResource('schools', SchoolController::class);
        });
    });
});

Authentication

Backend APIs should validate the access token and enforce authorization before returning protected data.

Example header:

Authorization: Bearer <ACCESS_TOKEN>

Authorization Rules

Rule	Description
Role-based access	Users must have the required role
Scope-based access	Users must only access data within their assigned school, supplier, or cafeteria scope
Sensitive action approval	Financial or credential-related actions may require stricter authorization
Audit logging	Sensitive actions must be recorded

Queue Jobs

Background jobs should be used for operations that should not block the user request.

Examples:

• Sending notifications
• Processing exports
• Running reconciliation tasks
• Sending emails or SMS
• Processing heavy reports
• Retrying external integration calls

Scheduled Tasks

Scheduled tasks should be documented with their purpose and frequency.

Task	Purpose	Frequency
Wallet reconciliation	Validate wallet and ledger consistency	TBD
Report generation	Prepare scheduled reports	TBD
Notification dispatch	Send queued notifications	TBD
Cleanup jobs	Remove expired temporary records	TBD

Logs

Application logs should be used for troubleshooting and audit support.

Common log locations:

storage/logs/laravel.log

Useful commands:

tail -f storage/logs/laravel.log
php artisan about
php artisan route:list
php artisan queue:failed

Cache

Laravel cache may be used for configuration, routes, views, sessions, and frequently accessed data.

Common commands:

php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan cache:clear
php artisan config:clear

Database Migrations

Migration rules:

• Review migrations before production deployment.
• Avoid destructive migrations without a backup.
• Test migrations on staging before production.
• Use --force only in controlled production deployment.

Example:

php artisan migrate --force

External Integrations

Document external integrations without exposing credentials.

Integration	Purpose	Notes
SMS Provider	OTP and notifications	Do not document API keys
Payment Gateway	Payment processing	Do not document merchant secrets
Email Service	Email notifications	Do not document SMTP password
Object Storage	Attachments and exports	Do not document access keys

Error Handling

API errors should return consistent responses.

Example:

{
  "message": "Unauthorized action.",
  "code": "AUTHORIZATION_ERROR",
  "reference_id": "REF-EXAMPLE-001"
}

Security Rules

• Do not expose stack traces in production.
• Do not store secrets in code.
• Do not document real .env values.
• Do not log passwords, tokens, OTP values, or private keys.
• Enforce RBAC and tenant isolation across all queries.
• Validate all user input.
• Rate-limit sensitive endpoints such as login and OTP.

Operational Checklist

Before production release:

• Confirm .env values are correct.
• Confirm migrations are reviewed.
• Confirm queue workers are running.
• Confirm Redis is reachable.
• Confirm storage permissions are correct.
• Confirm logs are writable.
• Confirm critical API endpoints work.
• Confirm no debug mode is enabled in production.