Document Management System API

This repository contains a Laravel 12 based backend for managing branches, departments, folders, document types and secure Cloudinary backed uploads with token-based authentication powered by Laravel Sanctum + HTTP-only refresh tokens.

Features

• API versioning (/api/v1/...) enforced through a custom middleware.
• Role based access control (SUPER_ADMIN, BRANCH_ADMIN, DEPARTMENT_ADMIN, DOCUMENT_CONTROLLER, USER).
• Branch, department, shelf, folder, document type, permission, role and document upload endpoints.
• Cloudinary signature generation + webhook to finalize uploads.
• Refresh token store with secure HTTP-only cookies.
• Caching for frequently accessed document types.
• Comprehensive database seeding for demo data (branches, departments, folders, documents, permissions, roles, users).
• Feature + unit tests (Auth, Branch, Document upload, Refresh token service).
• Postman collection for quick endpoint exploration (docs/postman/document-management.postman_collection.json).

Getting Started

Requirements

• PHP 8.3+
• Composer 2.6+
• MongoDB (default) - MongoDB server must be running

Installation

composer install
cp .env.example .env   # configure MongoDB connection in .env
php artisan key:generate

Environment

The .env file should include MongoDB connection settings and other required keys:

DB_CONNECTION=mongodb
DB_HOST=127.0.0.1
DB_PORT=27017
DB_DATABASE=event_booking
DB_USERNAME=
DB_PASSWORD=
DB_AUTHENTICATION_DATABASE=admin

API_VERSION=v1
SANCTUM_ACCESS_TOKEN_TTL=60
REFRESH_TOKEN_TTL_DAYS=30
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=
CLOUDINARY_UPLOAD_PRESET=

Populate the MongoDB connection details and Cloudinary credentials to enable functionality.

Database & Seeding

php artisan migrate --seed

Seeding creates:

• 2 SUPER_ADMINs ([email protected], [email protected], password Password@123)
• 3 branch admins, 10 department admins, 10 standard users
• 3 branches, 6 departments, 12 shelves, 36 folders
• 4 document types and 20 sample documents

Running the API

php artisan serve

All endpoints are available under http://localhost:8000/api/v1.

Tests

php artisan test

Postman Collection

Import docs/postman/document-management.postman_collection.json. It contains examples for:

• Auth (register/login/refresh/logout/forgot/reset)
• Branch + Department CRUD
• Shelf/Folder/Document Type endpoints
• Document upload + webhook
• Permission, Role, and User Role assignment

Notable Directories

app/Http/Controllers/Api        # REST controllers
app/Http/Requests               # DTO-style request validation
app/Http/Middleware             # API version + role guards
app/Services                    # Cloudinary + refresh token services
app/Traits                      # Common query scopes
database/migrations             # Schema for branches, departments, documents, etc.
database/seeders                # Demo data
tests/Feature & tests/Unit      # Automated coverage

Workflow Notes

• All responses share a consistent { status, message, data } schema via BaseApiController.
• Routes live in routes/api.php, grouped by version, and protected with auth:sanctum + role middleware.
• Sanctum token TTL is controlled by SANCTUM_ACCESS_TOKEN_TTL and refresh cookies by REFRESH_TOKEN_TTL_DAYS.

License

MIT © 2025

Authour

Prince