Queues and Jobs

Purpose

This page documents background job processing in Maqsafy, including queue responsibilities, job types, retry behavior, monitoring, and troubleshooting.

Why Queues Are Used

Queues are used to move slow or non-critical work outside the main user request.

Examples:

• Sending SMS or email notifications
• Processing reports and exports
• Handling external integration retries
• Processing wallet reconciliation tasks
• Dispatching order status notifications
• Running scheduled background operations

Queue Driver

Item	Value
Recommended Driver	Redis
Alternative Driver	Database
Production Recommendation	Use Redis for better performance and scalability

Common Queue Jobs

Job Type	Purpose
Notification Jobs	Send SMS, email, or in-dashboard notifications
Export Jobs	Generate Excel, CSV, or PDF reports
Reconciliation Jobs	Validate wallet and ledger consistency
Integration Jobs	Retry failed external API calls
Cleanup Jobs	Remove expired temporary records
Report Jobs	Generate heavy reports outside the request cycle

Laravel Queue Commands

php artisan queue:work
php artisan queue:restart
php artisan queue:failed
php artisan queue:retry all
php artisan queue:flush

Queue Worker Example

php artisan queue:work redis --queue=default --tries=3 --timeout=120

Failed Jobs

Failed jobs must be reviewed regularly.

php artisan queue:failed

Retry a specific failed job:

php artisan queue:retry <job-id>

Retry all failed jobs:

php artisan queue:retry all

Queue Monitoring

Monitor the following:

Metric	Reason
Pending jobs	Detect backlog
Failed jobs	Detect recurring failures
Job duration	Identify slow jobs
Retry count	Detect unstable integrations
Worker status	Confirm processing is active

Supervisor / Process Manager

In production, queue workers should be managed by a process manager.

Example checks:

sudo supervisorctl status
sudo supervisorctl restart all

If Docker is used, queue workers may run as separate containers.

docker ps
docker logs <queue-worker-container>

Retry Rules

• Retry external integration failures only when safe.
• Do not retry payment-related jobs without idempotency controls.
• Failed financial jobs must be reviewed before manual retry.
• Jobs should include clear logs and reference IDs.

Idempotency

Jobs that affect financial records, wallet balances, refunds, or external payments must be idempotent.

This means the same job should not create duplicate financial effects if it runs more than once.

Troubleshooting

Jobs Are Not Processing

Check:

php artisan queue:failed
php artisan queue:work
php artisan queue:restart

Possible causes:

• Queue worker is stopped
• Redis is unavailable
• Queue connection is misconfigured
• Job is failing repeatedly
• Process manager is not running

Jobs Are Slow

Check:

• Database query performance
• External API response time
• Queue backlog
• Worker timeout
• Job payload size

Security Rules

• Do not log access tokens.
• Do not log OTP values.
• Do not log payment secrets.
• Do not log full customer personal data.
• Use reference IDs for tracing sensitive processes.