Enterprise Laravel Architecture

Sales Claim Management
System — Project Oxygen

Production-ready modular monolith covering BPE, BPEC & BPEP workflows with enterprise-grade scalability, auditability, and financial accuracy.

Laravel 12+ PHP 8.3+ PostgreSQL Redis Sanctum/JWT REST API v1 Event-Driven RBAC Multi-Tenant Ready
15
Business Modules
9
Role Hierarchies
3
Workflows (BPE/EC/EP)
∞
Scalability
System Architecture
Layered System Architecture

Clean separation of concerns across infrastructure, application, and domain layers

Client Layer
Entry points & consumers
Web Browser (SPA/SSR) Third-party API Consumers ERP System Excel Import Agent
API Gateway
Request routing & security
Nginx Reverse Proxy Rate Limiting (Redis) Sanctum Auth Middleware API Versioning (v1/v2) CORS Policy Request Throttling
Application Layer
HTTP, routing, middleware
Route Groups (api/v1) Form Request Validators API Resource Transformers RBAC Policies Module Controllers Exception Handler
Domain Layer
Business logic & rules
Service Classes Action Classes Domain Events DTOs Enums Traits Calculation Engine Validation Engine Approval Workflow
Infrastructure
Cross-cutting concerns
Repository Pattern Eloquent ORM Queue Workers (Redis) Scheduled Jobs Event Listeners Notification Channels Observers Caching Strategy
Storage Layer
Persistence & caching
PostgreSQL (Primary DB) Redis (Cache/Queues) S3/MinIO (Documents) Elasticsearch (Search/Logs) DB Read Replicas
External Integrations
Third-party systems
ERP API (SAP/Tally) Excel/CSV Import Email (SMTP/SES) SMS Gateway Push Notifications (FCM) Payment Gateway Cloud Storage (S3)
Claim Lifecycle
End-to-End Claim Processing Workflow

From submission to disbursement — BPE / BPEC / BPEP pipeline

BPE Workflow (Direct Sales Agent)
1
Claim Submission
BPE submits claim with stockist & pharmacy data
2
Rate Validation
System validates vs Rate Master (Primary/Secondary)
3
Auto-Sync Check
ERP/Excel data sync verification
4
Calculation Engine
Margin calc, deductions, NRV adjustments
5
ABM Review
First-level approval & validation
6
RBM → ZBM
Escalation & percentage approval
7
Finance Approval
AGM/COO/MD based on threshold
8
Disbursement
Cheque / NEFT / Gift Card / Reimbursement
📋
BPE Workflow
Business Promotion Executive — Direct field sales claim with stockist-wise validation, primary/secondary rate comparison, and pharmacy-level supply proof.
Stockist Validation Pharmacy Proof Primary Rates Sales Return Deduction
📊
BPEC Workflow
Business Promotion Executive (Channel) — Channel partner claim with secondary rate basis, stockist margin calculations, and advance deduction reconciliation.
Channel Partner Secondary Rates Advance Deduction Margin Calc
🎯
BPEP Workflow
Business Promotion Executive (Pharma) — Pharma-specific claim with NRV adjustments, percentage-based approvals, and multi-level finance gateway validation.
NRV Adjustment % Approval Finance Gate Multi-Level
Business Modules
15 Independent Business Modules

Loosely coupled — independently deployable — domain-driven

View All Modules →
🔐
Auth
JWT/Sanctum authentication, token management, password reset, 2FA, device management, session control.
SanctumJWT2FAOAuth2
12 files · 4 migrations→
👥
Users
User management, profile, territory assignment, hierarchy mapping, status management, BPE/ABM/RBM profiles.
HierarchyTerritoryProfiles
18 files · 6 migrations→
🛡️
Roles & RBAC
Role hierarchy (ABM→RBM→SRBM→ZBM→AGM→COO→MD), permissions matrix, policy guards, Spatie integration.
SpatiePoliciesGates
14 files · 3 migrations→
💹
Rate Management
Rate master (primary/secondary), product-wise rate quotation, effective date management, version history, approval workflow for rate changes.
Primary RateSecondary RateVersioning
20 files · 5 migrations→
📑
Claims
Central claim lifecycle management for BPE/BPEC/BPEP. Draft, submitted, validated, approved, disbursed states with full audit trail.
BPEBPECBPEPLifecycle
35 files · 8 migrations→
✅
Validation Engine
Stockist-wise and pharmacy-wise validation, supply proof verification, cross-check with ERP/Excel data, duplicate detection.
StockistPharmacySupply Proof
16 files · 2 migrations→
🧮
Calculation Engine
Primary vs secondary rate comparison, stockist margin, sales return deductions, percentage approvals, NRV adjustments, advance deductions.
MarginsNRVDeductionsPrecision
22 files · 1 migration→
📬
Approval Workflow
Multi-level configurable approval chains, threshold-based escalation, delegation, SLA tracking, reminder automation.
Multi-LevelSLADelegation
24 files · 4 migrations→
🔄
Auto-Sync Engine
Selective ERP/Excel/API data synchronization with conflict resolution, field-level mapping, retry logic, and sync audit logs.
ERPExcelSelective Sync
18 files · 3 migrations→
📁
Documents
Supply proof, invoices, pharmacy bills, signed documents with S3 storage, virus scanning, watermarking, OCR metadata extraction.
S3/MinIOOCRVirus Scan
14 files · 2 migrations→
💳
Disbursement
Reimbursement processing, cheque issuance, online NEFT/IMPS transfers, gift card management, batch disbursement, reconciliation.
ChequeNEFTGift CardBatch
20 files · 5 migrations→
📈
Reports
Role-based dashboards, claim analytics, financial summaries, territory performance, export to Excel/PDF, scheduled report delivery.
DashboardsExcel ExportPDF
16 files · 0 migrations→
🔔
Notifications
Multi-channel notifications (email, SMS, push, in-app), template management, delivery tracking, preference management, bulk notifications.
EmailSMSPushIn-App
12 files · 2 migrations→
📝
Audit Logs
Immutable audit trail for all financial actions, RBAC changes, approval decisions, data modifications with before/after snapshots.
ImmutableBefore/AfterGDPR
10 files · 2 migrations→
🔌
Integrations
Pluggable integration adapters for ERP (SAP/Tally), payment gateways, cloud storage, email providers with circuit breaker pattern.
SAPTallyCircuit Breaker
28 files · 1 migration→
RBAC
Role Hierarchy & Permissions

9 role levels with granular permission matrices and approval thresholds

L1
BPE / BPEC / BPEP
  • Submit claims
  • Upload documents
  • View own claims
  • Track disbursement
L2
ABM
  • Validate team claims
  • First-level approve
  • Reject with reason
  • Territory reports
L3
RBM
  • Regional approval
  • Rate quotation approve
  • Override ABM decisions
  • Regional dashboards
L4
SRBM
  • Senior regional approval
  • Large claim thresholds
  • Multi-territory view
  • Exception management
L5
ZBM
  • Zonal approval authority
  • Percentage-based approval
  • Zonal analytics
  • Escalation management
L6
AGM
  • National claim approval
  • Rate master approval
  • Financial limits: ₹5L
  • Bulk disbursement
L7
COO
  • Executive approval
  • Policy override
  • Financial limits: ₹25L
  • All reporting access
L8
MD
  • Ultimate approval authority
  • No financial limits
  • System configuration
  • Full audit access
SYS
BIS Team / HO
  • System administration
  • Rate master management
  • Integration management
  • Audit log access
Technology
Production Tech Stack

Carefully selected enterprise-grade technologies for long-term maintainability

🔴
Laravel 12+
^12.0
🐘
PHP 8.3+
^8.3
🐘
PostgreSQL 16
^16.0
⚡
Redis 7
^7.0
🌐
Nginx
Reverse Proxy
🔑
Laravel Sanctum
^4.0
📦
Spatie Permissions
^6.0
📊
Laravel Excel
^3.1
📄
DomPDF / Snappy
PDF reports
🔍
Laravel Scout
Elasticsearch
🧪
Pest PHP
Testing
🚀
GitHub Actions
CI/CD
Data Layer
Core Database Schema

PostgreSQL with proper indexing, constraints, and relationship design

⬡ users
idbigint PK
employee_codevarchar(20) UNIQUE
namevarchar(255)
emailvarchar UNIQUE
role_idFK → roles
manager_idFK → users
zone_idFK → zones
statusenum
created_attimestamp
⬡ claims
idbigint PK
claim_numbervarchar UNIQUE
claimant_idFK → users
claim_typeenum(bpe,bpec,bpep)
statusenum(12 states)
gross_amountdecimal(15,4)
net_payabledecimal(15,4)
period_idFK → claim_periods
submitted_attimestamp
⬡ rate_masters
idbigint PK
product_idFK → products
rate_typeenum(primary,secondary)
rate_valuedecimal(10,4)
effective_fromdate
effective_todate nullable
approved_byFK → users
versioninteger
⬡ approval_flows
idbigint PK
claim_idFK → claims
approver_idFK → users
levelinteger
actionenum(approve,reject,delegate)
remarkstext
acted_attimestamp
sla_deadlinetimestamp
⬡ claim_line_items
idbigint PK
claim_idFK → claims
product_idFK → products
stockist_idFK → stockists
quantitydecimal(12,3)
primary_ratedecimal(10,4)
secondary_ratedecimal(10,4)
calculated_amountdecimal(15,4)
⬡ audit_logs
idbigint PK
user_idFK → users
eventvarchar(100)
auditable_typemorphs
auditable_idbigint
old_valuesjsonb
new_valuesjsonb
ip_addressinet
⬡ disbursements
idbigint PK
claim_idFK → claims
methodenum(cheque,neft,gift_card,reimbursement)
amountdecimal(15,4)
reference_numbervarchar
statusenum
disbursed_attimestamp
⬡ sync_logs
idbigint PK
sourceenum(erp,excel,api)
entity_typevarchar(100)
records_syncedinteger
conflictsjsonb
statusenum
started_attimestamp
completed_attimestamp
Project Structure
Modular Folder Architecture

Clean domain-driven module organization with consistent internal structure

# /var/www/projectoxygen — Laravel Modular Monolith ├── app/ │ ├── Modules/ # Business domain modules │ │ ├── Auth/ │ │ │ ├── Controllers/ │ │ │ ├── Services/AuthService.php │ │ │ ├── Repositories/ │ │ │ ├── DTOs/LoginDTO.php │ │ │ ├── Actions/LoginAction.php │ │ │ ├── Events/UserLoggedIn.php │ │ │ ├── Listeners/ │ │ │ ├── Notifications/ │ │ │ ├── Requests/LoginRequest.php │ │ │ ├── Resources/ │ │ │ ├── Policies/ │ │ │ ├── Enums/TokenAbilityEnum.php │ │ │ ├── Traits/ │ │ │ ├── Jobs/ │ │ │ ├── Models/PersonalAccessToken.php │ │ │ ├── Migrations/ │ │ │ └── routes.php │ │ ├── Claims/ # Core claim lifecycle module │ │ │ ├── Controllers/ClaimController.php │ │ │ ├── Services/ClaimService.php │ │ │ ├── Repositories/ClaimRepository.php │ │ │ ├── DTOs/CreateClaimDTO.php │ │ │ ├── Actions/SubmitClaimAction.php │ │ │ ├── Events/ClaimSubmitted.php │ │ │ ├── Enums/ClaimStatusEnum.php │ │ │ ├── Enums/ClaimTypeEnum.php │ │ │ ├── Models/Claim.php │ │ │ ├── Models/ClaimLineItem.php │ │ │ ├── Policies/ClaimPolicy.php │ │ │ ├── Resources/ClaimResource.php │ │ │ ├── Requests/CreateClaimRequest.php │ │ │ ├── Jobs/ProcessClaimJob.php │ │ │ └── routes.php │ │ ├── CalculationEngine/ │ │ │ ├── Services/CalculationService.php │ │ │ ├── Services/MarginCalculator.php │ │ │ ├── Services/DeductionService.php │ │ │ ├── Services/NrvAdjustmentService.php │ │ │ ├── DTOs/CalculationResultDTO.php │ │ │ └── Traits/MoneyPrecisionTrait.php │ │ └── ... (15 total modules) │ ├── Shared/ # Cross-module shared code │ │ ├── Contracts/ │ │ ├── Traits/ │ │ ├── Helpers/ │ │ └── Exceptions/ │ ├── Http/ │ │ ├── Middleware/ │ │ └── Kernel.php │ └── Providers/ │ ├── AppServiceProvider.php │ └── ModuleServiceProvider.php ├── database/ │ ├── migrations/ │ ├── seeders/ │ └── factories/ ├── tests/ │ ├── Unit/Modules/ │ ├── Feature/Modules/ │ └── Integration/ ├── .github/workflows/ │ ├── ci.yml │ └── deploy.yml ├── composer.json └── .env.example
Infrastructure
Cloud Deployment Strategy

Horizontally scalable, zero-downtime deployments on cloud infrastructure

🖥️
Server Stack (Production)
PHP-FPM 8.3, Nginx reverse proxy, PostgreSQL 16, Redis 7, supervisor-managed queue workers and scheduler.
PHP-FPM 8.3NginxSupervisorRedis
☸️
Kubernetes (Production)
K8s deployments with auto-scaling, rolling updates, health probes, resource limits, and namespace isolation.
HPARolling UpdateNamespaces
🚀
CI/CD Pipeline
GitHub Actions: test → lint → build → staging deploy → smoke test → production deploy with approval gate.
GitHub ActionsPest TestsZero Downtime
📊
Observability
Centralized logging (Elasticsearch), metrics (Prometheus/Grafana), distributed tracing (Jaeger), alerting (PagerDuty).
ELK StackPrometheusGrafana