Table of Contents

1. Executive Summary & Scope

This document defines the complete technical architecture for the Mariinox CRM & Scrap Operations Platform, re-platformed from ERPNext/Frappe to a purpose-built Laravel 11 + React 18 stack. It is the primary reference for database schema design, API contracts, sprint planning, and infrastructure provisioning.

1.1 Scope — This Document

• Lead Capture (inbound call, web form, WhatsApp chatbot)
• Lead Assignment & Master Queue Engine
• Pipeline Management (Car/Truck 11-stage, Bike 10-stage)
• Deal Types & Customer Case Types
• Document Collection, OCR, Fraud Detection & Verification
• Pricing Engine (Scrap Value calculation, overrides, audit)
• Payment CRM Triggers (UTR, receipts, stage gating)
• SLA & Escalation Engine
• WhatsApp + SMS Notification Engine
• Dashboards — Agent, Admin, Leadboard, Analytics (8 dashboards)
• Role-Based Access Control — 6 pipeline roles + dynamic field-level RBAC
• Immutable Audit Logging + Aadhaar Compliance
• AWS Infrastructure (ap-south-1)

1.2 Out of Scope

• Customer self-service portal
• Logistics portal & driver app
• Government scrapping portal connector (Phase 2)
• Payment gateway disbursement execution (NEFT/IMPS)
• Native mobile app (iOS/Android)

1.3 Key Constraints

2. Technology Stack Rationale

The platform is intentionally separated into a stateless API layer (Laravel) and a stateful UI layer (React SPA). This allows independent scaling and clear contract boundaries for future mobile apps or third-party integrations.

3. System Architecture Overview

3.1 Deployment Architecture

3.2 Request Flow

Browser → CloudFront → ALB → Nginx (EC2) → PHP-FPM / Laravel Router → Controller → Service Layer → Repository → MySQL / Redis / S3

Background jobs: Laravel Horizon (Redis) → Job Class → External APIs (VAHAN, Textract, WhatsApp, SMS)

3.3 Laravel Application Structure

4. Module Breakdown

4.1 Lead Capture Module

4.2 Assignment & Queue Module

Agent Status Model

Bandwidth (active lead count) = leads in stages: Fresh + Interested + Verbal Commitment assigned to that agent.

Agent Capacity Benchmarks (configurable per agent)

5-Layer Assignment Rules Engine

Layers are evaluated in strict order. The engine stops at the first layer that produces a unique eligible agent.

Genuine Attempt Qualifier

4.3 Pipeline Module

• Car / Truck (11 stages): Fresh → Interested → Verbal Commitment → Document Initiated → Doc Verification Pending → Document Verified → Scrap Value Paid → Assigned to Logistic → Pickup Scheduled → Assigned to Agent → Pickup Done
• Bike / 2W (10 stages): Same but COD With Trade disabled; Scrap Value Paid occurs after Pickup Scheduled

Stage transitions are gated by: role permission check → mandatory field validation → business rule validation → audit log entry.

4.4 SLA Engine Module

5. Database Schema — Core Tables

5.1 users

Indexes: email (unique), role, is_active, team_id

5.2 leads

Indexes: lead_number, stage, vehicle_type, assigned_to, stage_entered_at, sla_breached, composite (stage+assigned_to)

5.3 lead_vehicle_details

One-to-one with leads. Stores all VAHAN + manual vehicle data. Pricing formula: Scrap Value = Kerb Weight (kg) × Metal Rate (₹/kg) × Condition Modifier

5.4 lead_contacts & 5.5 lead_attribution

6. Database Schema — Module Tables

Key module-specific tables. Full 22-table ERD finalized in Sprint 1, Week 2.

7. API Design Conventions

7.1 Base URL & Standards

• Base URL: /api/v1/
• Auth: Laravel Sanctum token in Authorization: Bearer {token} header
• Response envelope: { data, meta, errors }
• Status codes: 200 / 201 / 422 / 401 / 403 / 404 / 500

7.2 Core API Endpoints

8. Authentication & RBAC

8.1 Pipeline Role Definitions

// Migration snippet — permissions table
Schema::create('permissions', function (Blueprint $table) {
    $table->id();
    $table->foreignId('role_id')->constrained()->cascadeOnDelete();
    $table->foreignId('module_id')->constrained()->cascadeOnDelete();
    $table->foreignId('field_id')->nullable()->constrained()->cascadeOnDelete();
    $table->boolean('can_view')->default(false);
    $table->boolean('can_edit')->default(false);
    $table->unique(['role_id', 'module_id', 'field_id']);
    $table->index(['role_id', 'module_id']);
});

8.4 Eloquent Models & Relationships (Step 2)

// Role.php
class Role extends Model {
    public function permissions(): HasMany {
        return $this->hasMany(Permission::class);
    }
}

// Module.php
class Module extends Model {
    public function fields(): HasMany {
        return $this->hasMany(Field::class);
    }
}

// Field.php
class Field extends Model {
    public function module(): BelongsTo {
        return $this->belongsTo(Module::class);
    }
}

// Permission.php
class Permission extends Model {
    public function role(): BelongsTo    { return $this->belongsTo(Role::class); }
    public function module(): BelongsTo  { return $this->belongsTo(Module::class); }
    public function field(): BelongsTo   { return $this->belongsTo(Field::class); }
}

8.5 FieldSyncService (Step 3)

// App\Services\FieldSyncService.php
class FieldSyncService {
    public function sync(string $moduleSlug): array {
        $module = Module::where('slug', $moduleSlug)->firstOrFail();
        $columns = Schema::getColumnListing($moduleSlug);

        $synced = 0; $skipped = 0;
        foreach ($columns as $column) {
            $existing = Field::where('module_id', $module->id)
                             ->where('name', $column)->first();
            if ($existing) {
                // Preserve manual label/type overrides
                $skipped++; continue;
            }
            Field::create([
                'module_id' => $module->id,
                'name'      => $column,
                'label'     => Str::title(str_replace('_', ' ', $column)),
                'type'      => $this->inferType($column),
                'is_active' => true,
            ]);
            $synced++;
        }
        return ['synced' => $synced, 'skipped' => $skipped];
    }

    private function inferType(string $column): string {
        if (str_ends_with($column, '_at'))    return 'date';
        if (str_ends_with($column, '_id'))    return 'number';
        if (str_contains($column, 'amount') || str_contains($column, 'value')) return 'number';
        if (str_contains($column, 'is_') || str_contains($column, 'has_')) return 'boolean';
        return 'text';
    }
}

// App\Services\PermissionService.php
class PermissionService {
    public function canAccessField(User $user, string $moduleSlug, string $fieldName, string $action = 'view'): bool {
        $role = $user->role;
        if (!$role) return false;

        // Admin always has full access
        if ($role->slug === 'admin') return true;

        $map = $this->getPermissionMap($role->id, $moduleSlug);

        // Check module-level permission first (field_id = null)
        if (!($map['__module__']['can_view'] ?? false)) return false;

        // Check field-level permission
        $fieldPerms = $map[$fieldName] ?? null;
        if (!$fieldPerms) return false;

        return match($action) {
            'view' => (bool) $fieldPerms['can_view'],
            'edit' => (bool) $fieldPerms['can_edit'],
            default => false,
        };
    }

    private function getPermissionMap(int $roleId, string $moduleSlug): array {
        $cacheKey = "rbac:role:{$roleId}:module:{$moduleSlug}";

        return Cache::remember($cacheKey, now()->addMinutes(5), function () use ($roleId, $moduleSlug) {
            $module = Module::where('slug', $moduleSlug)->firstOrFail();
            $perms  = Permission::with('field')
                          ->where('role_id', $roleId)
                          ->where('module_id', $module->id)
                          ->get();
            $map = [];
            foreach ($perms as $perm) {
                $key = $perm->field_id ? $perm->field->name : '__module__';
                $map[$key] = ['can_view' => $perm->can_view, 'can_edit' => $perm->can_edit];
            }
            return $map;
        });
    }

    public function bustCache(int $roleId, string $moduleSlug): void {
        Cache::forget("rbac:role:{$roleId}:module:{$moduleSlug}");
    }

    // Bulk filter: removes inaccessible fields from an array
    public function filterFields(User $user, string $moduleSlug, array $data): array {
        return array_filter($data, function ($value, $key) use ($user, $moduleSlug) {
            return $this->canAccessField($user, $moduleSlug, $key, 'view');
        }, ARRAY_FILTER_USE_BOTH);
    }
}

// App\Http\Middleware\CheckModuleAccess.php
class CheckModuleAccess {
    public function handle(Request $request, Closure $next, string $moduleSlug): Response {
        $user = $request->user();
        if (!$user) return response()->json(['error' => 'Unauthenticated'], 401);

        $service = app(PermissionService::class);
        if (!$service->canAccessField($user, $moduleSlug, '__module__', 'view')) {
            return response()->json(['error' => 'Access denied to module: ' . $moduleSlug], 403);
        }
        return $next($request);
    }
}

// routes/api.php — usage
Route::middleware(['auth:sanctum', 'module:leads'])->group(function () {
    Route::apiResource('leads', LeadController::class);
});
Route::middleware(['auth:sanctum', 'module:customers'])->group(function () {
    Route::apiResource('customers', CustomerController::class);
});

// AppServiceProvider.php — register Blade directive
Blade::if('canField', function (string $module, string $field, string $action = 'view') {
    $user    = auth()->user();
    $service = app(PermissionService::class);
    return $user && $service->canAccessField($user, $module, $field, $action);
});

// Global helper (Helpers.php)
function canField(string $module, string $field, string $action = 'view'): bool {
    $user = auth()->user();
    if (!$user) return false;
    return app(PermissionService::class)->canAccessField($user, $module, $field, $action);
}

// Usage in Blade templates

                    @canField('customers', 'credit_limit', 'view')
                    
Credit Limit: {{ $customer->credit_limit }}
                    @endcanField

                    @canField('leads', 'aadhaar_number', 'edit')
                    
                    @else
                        ****  ****  ****
                        @endcanField
                        

8.10 Controller Integration (Step 8)

// LeadController.php — show()
public function show(Lead $lead): JsonResponse {
    $this->authorize('view', $lead); // Laravel Policy (pipeline role gate)

    $data = $lead->toArray();

    // Dynamic RBAC: strip fields user cannot view
    $filtered = app(PermissionService::class)->filterFields(auth()->user(), 'leads', $data);

    return response()->json(['data' => $filtered]);
}

// LeadController.php — update()
public function update(UpdateLeadRequest $request, Lead $lead): JsonResponse {
    $this->authorize('update', $lead);

    // Only allow fields where can_edit = true
    $allowedFields = array_filter($request->all(), function ($key) {
        return canField('leads', $key, 'edit');
    }, ARRAY_FILTER_USE_KEY);

    $lead->update($allowedFields);
    return response()->json(['data' => $lead->fresh()]);
}

8.11 API Response Protection (Step 9)

// BaseApiController.php
protected function permissionFilteredResponse(User $user, string $module, array $data): array {
    return app(PermissionService::class)->filterFields($user, $module, $data);
}

// For collection responses (e.g. GET /leads index)
protected function filterCollection(User $user, string $module, Collection $items): array {
    return $items->map(fn($item) =>
        $this->permissionFilteredResponse($user, $module, $item->toArray())
    )->toArray();
}

// Pipeline: Controller → PermissionService::filterFields → JsonResponse
// No restricted field ever reaches the wire — server-side enforcement only

8.13 Advanced Enhancements

8.14 Laravel Policy Layer — Pipeline Stage Gates

// LeadPolicy.php
public function view(User $user, Lead $lead): bool {
    if ($user->role->slug === 'agent')      return $lead->assigned_to === $user->id;
    if ($user->role->slug === 'supervisor') return $lead->team_id === $user->team_id;
    return in_array($user->role->slug, ['admin', 'verification', 'finance', 'logistics']);
}

public function transition(User $user, Lead $lead, string $toStage): bool {
    $allowedRoles = PipelineConfig::stageAllowedRoles($lead->vehicle_type, $toStage);
    return in_array($user->role->slug, $allowedRoles);
}

8.15 Session & Token Management

• Laravel Sanctum SPA tokens — stored in HttpOnly cookies for web app; Bearer token for API clients
• Token expiry: 8 hours active session; 24 hours with remember-me
• Agent heartbeat ping: POST /api/v1/auth/heartbeat every 5 minutes — extends session + records active time in agent_sessions
• 10-minute inactivity = Idle status; 60-minute no-heartbeat = forced logout (configurable in system_configs)
• Admin can view active sessions in Admin Command Centre; terminate any session from the UI

9. Third-Party Integrations

10. Infrastructure & DevOps

10.1 AWS Resource Sizing — Phase 1 Launch

10.2 CI/CD Pipeline

GitHub Actions → Build PHP + React → Run PHPUnit + Jest → Build Docker image → Push to ECR → Deploy to Staging → Smoke test → Manual approval gate → Deploy to Production

10.3 Security Controls

• WAF: AWS WAF on ALB — rate limiting, SQL injection, XSS rules
• Secrets: AWS Secrets Manager for all API keys, DB credentials, S3 KMS key ARN
• VPC: App and DB tiers in private subnets; NAT Gateway for outbound-only internet access
• Aadhaar compliance: No raw Aadhaar in logs; AES-256 at rest; field-level API masking; legal review before go-live
• Penetration test: RBAC penetration test in Week 9 before Phase 1 UAT — all 6 roles × 47 endpoints

11. Sprint Plan — Phase 1 (Weeks 1–11)

11.0 Team Composition

Sprint Schedule Overview

12. Sprint Plan — Phase 2 (Weeks 12–18) | 60 PD | 120 SP

13. Sprint Plan — Phase 3 (Weeks 19–23) | 84 PD | 168 SP

Grand Total — All Phases: 577 + 60 + 84 = 721 Person-Days | 1,154 + 120 + 168 = 1,442 Story Points

14. Non-Functional Requirements

15. Risk Register

Legend: Red = High   Orange = Medium — All risks reviewed at each sprint retrospective.