APM (Approvals Management) Documentation

Welcome to the APM (Approvals Management) documentation. This directory contains comprehensive guides for the Laravel-based Approvals Management System.

📚 Documentation Index

User Guides

• User Guide - Complete guide for creating and managing documents (Matrices, Memos, Requests)
• Approvers Guide - Guide for approvers on how to approve, return, or reject documents

API

• APM API Documentation - REST API guide: auth, endpoints, pending approvals with approval trails, actions, memo list, and examples.
• APM API (OpenAPI/Swagger) - OpenAPI 3.0 specification (full request/response schemas). Interactive docs: open /docs in the browser (e.g. http://localhost/staff/apm/docs).

Core Features

• Approval Trail Management - Complete guide to approval trail tracking and management (includes fixing promoted single-memo trails: apm:fix-single-memo-promoted-approval-trails)
• Approval Trail Archiving - How to archive old approval trails and manage storage
• Document Numbering System - Document number generation and management
• Document Number Management - Advanced document numbering features
• Signature Verification - Validate APM document signature hashes (lookup, verify, upload PDF)
• Change Tracking Feasibility - Change tracking implementation guide

Infrastructure & Deployment

• Environment variables (.env) - Sample .env template (.env.example), setup steps, and variable reference
• Deployment Guide - Production deployment instructions
• Queue Setup Guide - Laravel queue configuration and setup
• Queue Troubleshooting - Common queue issues and solutions
• Cron Setup - Cron job configuration for scheduled tasks
• Supervisor Setup Demo - Supervisor configuration for queue workers
• Database Backup System - Automatic database backups with retention policies and OneDrive integration

Notifications & Automation

• Daily Notifications Setup - Daily notification system configuration
• Firebase / FCM push (pending approvals) - Setup, API token registration, Artisan commands (notifications:test-fcm-pending-approvals, notifications:send-pending-approvals-fcm)
• Session Expiry Setup - Session expiration and management

System Improvements

• Sync Improvements - Data synchronization enhancements
• System Updates - Changelog of new features and updates (signature verification, etc.)
• Jobs and Commands - Background jobs, schedulers, and Artisan command reference (including apm:fix-single-memo-promoted-approval-trails)

🚀 Quick Commands

Queue Management

# Start queue worker
php artisan queue:work

# Process specific queue
php artisan queue:work --queue=high,default

# Restart queue workers
php artisan queue:restart

Cron Jobs

See Cron Setup Guide for complete cron configuration.

Key cron entries:

* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1

Artisan Commands

# Run migrations
php artisan migrate

# Run seeders
php artisan db:seed

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

Single memo / matrix promotion trail fix

From the apm/ directory. Repairs approval_trails for activities already converted to single memos (action labels and timestamps from activity_approval_trails). Full detail: Jobs and Commands → apm:fix-single-memo-promoted-approval-trails.

php artisan apm:fix-single-memo-promoted-approval-trails --dry-run
php artisan apm:fix-single-memo-promoted-approval-trails
php artisan apm:fix-single-memo-promoted-approval-trails --activity-id=118 --dry-run

Firebase (FCM) pending-approval pushes

From the apm/ directory. Full guide: FIREBASE_PUSH_NOTIFICATIONS.md.

# Test: list users with tokens + pending counts (no send)
php artisan notifications:test-fcm-pending-approvals --dry-run

# Test: send pending-approval FCM immediately (no queue worker required)
php artisan notifications:test-fcm-pending-approvals

# Production batch (queues jobs unless --sync)
php artisan notifications:send-pending-approvals-fcm
php artisan notifications:send-pending-approvals-fcm --sync

📖 Documentation by Topic

For Developers

1. APM API (approver apps / integrations)

- API Documentation - Auth, endpoints, approval trails, actions, and curl examples

- OpenAPI spec: APM_API_OPENAPI.yaml

- Interactive Swagger UI: visit /docs when the app is running (e.g. http://localhost/staff/apm/docs)

- See System Updates for API summary and changelog

1. Understanding Approval System

- Start with Approval Trail Management

- Review Document Numbering System

- Check Change Tracking Feasibility

1. Working with Queues

- Read Queue Setup Guide

- Troubleshoot with Queue Troubleshooting

- Configure Supervisor Setup

1. System Maintenance

- Review Approval Trail Archiving

- Check Sync Improvements

- See System Updates for recent features (including APM API and users sync)

For DevOps/System Administrators

1. Production Deployment

- Start with Deployment Guide

- Configure Cron Setup

- Set up Queue Workers

1. Monitoring & Maintenance

- Review Approval Trail Archiving

- Check Queue Troubleshooting

- Set up Database Backup System - Configure automatic backups and retention policies

1. Automation

- Configure Daily Notifications

- Set up Session Expiry

- Configure Database Backups - Automatic backup scheduling and cleanup

🔧 Common Tasks

Setting Up Queue Workers

See the Queue Setup Guide for detailed instructions.

Quick setup:

1. Install Supervisor: sudo apt-get install supervisor
2. Configure queue worker in Supervisor
3. Start Supervisor service
4. Monitor queue processing

Configuring Cron Jobs

See Cron Setup Guide for complete configuration.

Key points:

• Add Laravel scheduler to crontab
• Ensure proper permissions
• Monitor cron logs

Archiving Approval Trails

See Approval Trail Archiving for complete guide.

Quick reference:

• Archive old approval trails to reduce database size
• Maintain data integrity during archiving
• Restore archived data if needed

🐛 Troubleshooting

Common Issues

1. Queue not processing

- Check Queue Troubleshooting

- Verify Supervisor is running

- Check queue connection configuration

1. Cron jobs not running

- Verify crontab entry

- Check file permissions

- Review cron logs

1. Document numbers not generating

- Review Document Numbering System

- Check database configuration

- Verify sequence tables

1. Notifications not sending

- Check Daily Notifications Setup

- Verify queue is processing

- Review notification logs

📝 File Structure

apm/
├── documentation/          # All documentation (this directory)
├── app/
│   ├── Http/
│   │   └── Controllers/   # Laravel controllers
│   ├── Models/            # Eloquent models
│   ├── Jobs/              # Queue jobs
│   └── Console/
│       └── Commands/      # Artisan commands
├── database/
│   ├── migrations/        # Database migrations
│   └── seeders/          # Database seeders
├── resources/
│   └── views/            # Blade templates
└── routes/               # Route definitions

🔗 Related Resources

APM Module

• Main README: ../README.md
• Laravel Documentation: https://laravel.com/docs

Platform Documentation

• Main Documentation Hub: ../../documentation/README.md - Central documentation for the entire CBP platform

Related Modules

• Finance Module Documentation: ../../finance/documentation/ - Node.js/React Finance Management System documentation

- Frontend Architecture

- Server Architecture

- Migrations Guide

- Session Implementation

- Installation Guide

• Staff Portal Documentation:

- Environment Variables - Configuration guide

- Auth Module Improvements - Authentication features

- Shared Header Usage - Component documentation

📞 Support

For issues or questions:

1. Check the relevant documentation guide
2. Review troubleshooting sections
3. Check Laravel logs: storage/logs/laravel.log
4. Verify configuration files
5. Review queue logs if using queues

Last Updated: 2025

Version: 1.1.0