Backend Documentation

The Compliance Scorecard backend is built with Laravel 9.x, providing a robust REST API for the React frontend. It handles authentication, authorization, data management, and integrations with external services.

Laravel 9.x

Modern PHP framework with robust features

MySQL Database

Relational database with complex schemas

Auth0 Integration

Secure authentication and authorization

Project Structure

polygon-be/
├── app/
│   ├── Console/Commands/         # Artisan commands
│   ├── Enums/                   # PHP enums for constants
│   ├── Events/                  # Laravel events
│   ├── Exceptions/              # Custom exception handlers
│   ├── Http/
│   │   ├── Controllers/         # API controllers
│   │   ├── Middleware/          # Custom middleware
│   │   └── Resources/           # API resources
│   ├── Jobs/                    # Queue jobs
│   ├── Listeners/               # Event listeners
│   ├── Mail/                    # Mail templates
│   ├── Models/                  # Eloquent models
│   ├── Notifications/           # Laravel notifications
│   ├── Providers/               # Service providers
│   ├── Repositories/            # Data repositories
│   ├── Services/                # Business logic services
│   └── Util/                    # Helper utilities
├── config/                      # Configuration files
├── database/
│   ├── factories/               # Model factories
│   ├── migrations/              # Database migrations
│   └── seeders/                 # Database seeders
├── resources/views/             # Blade templates
├── routes/
│   ├── api.php                  # API routes
│   └── api/v3/ & api/v4/        # Versioned API routes
└── storage/                     # File storage

Technology Stack

Core Technologies

  • Laravel 9.x - PHP framework
  • PHP 8.3 - Programming language
  • MySQL - Primary database
  • Redis - Caching and sessions
  • Docker - Containerization

Key Packages

  • Auth0/Login - Authentication
  • Laravel Sanctum - API tokens
  • Stripe - Payment processing
  • AWS SDK - S3 file storage
  • Sentry - Error tracking

User Management System

User Model

The User model is the core of the authentication system, supporting multiple user types and roles.

// Key User Model Features
enum UserStatus: string {
    case ACTIVE = 'Active';
    case INACTIVE = 'Inactive';
    case INVITED = 'Invited';
}

enum UserRoleID: string {
    case MSP_ADMIN = '8QM9M7QM3';
    case PEER_GROUP_ADMIN = 'D2UDJIUKZ';
    case MSP_USER = 'JQM8PKQMX';
    case CLIENT_USER = 'Q2DXDK2KY';
    case AUDITOR = 'DAUDJIUKC';
}
User Relationships
  • → Company (belongsTo)
  • → Role (belongsTo)
  • → Contact (hasOne)
  • → UserPermission (hasOne)
  • → Pax8Provision (hasMany)
  • → Ssp (belongsToMany)

Key User Methods

Method Description Return Type
hasPermission($permissions) Check if user has specific permission(s) bool
getCurrentClientId() Get the current client ID for the user string|null
listOfClients() Get list of clients user has access to Collection
clientFeatureAccess() Get array of feature permissions for current client array
isBlocked() Check if user domain is blocked bool

Company & Client Architecture

Hierarchical Structure

Company (MSP) → Clients (End Customers) → Users/Contacts

Company Features
  • Subscription management (Stripe)
  • Billing and payment tracking
  • Feature toggles and limits
  • Auto-logout timer settings
  • PDF download settings
Client Features
  • Status management (Active/Inactive)
  • Email delivery preferences
  • MS Graph integration settings
  • Asset synchronization options
  • Country-specific configurations
Key Enums
  • CompanyStatus
  • ClientStatus
  • StripeSubscriptionStatus
  • CompanySubscriptionPackage
  • EmailDeliveryPreference

Policy Management System

The policy system manages the complete lifecycle of compliance policies from creation to approval and publication.

Core Policy Models

Model Purpose
Policy Main policy entity with metadata
PolicyDocument Versioned policy content and state
PolicyDocumentSection Individual policy sections
PolicyReview Policy approval workflow
PolicySectionSetting Section configuration and visibility
PolicyAdoptionQuestion Questions for policy adoption

Policy Workflow States

Policy Document States:
├── draft          # Initial creation
├── pending_review # Submitted for approval
├── approved       # Approved by reviewer
├── published      # Live and active
├── rejected       # Rejected by reviewer
└── archived       # Deprecated/removed

Key Features

  • Version control and comparison
  • Rich text editing with sections
  • Approval workflow with reviewers
  • PDF generation and export
  • Policy adoption campaigns
  • Integration with templates

Assessment System

The assessment system provides comprehensive compliance assessment capabilities with customizable templates and automated scoring.

Assessment Architecture

Templates
  • AssessmentTemplate
  • AssessmentTemplateQuestion
  • AssessmentTemplateQuestionOption
  • AssessmentType
Events (Instances)
  • AssessmentEvent
  • AssessmentEventQuestion
  • AssessmentEventQuestionRaci
  • AssessmentEventQuestionVendorTool
Scoring
  • AssessmentScoring
  • AssessmentItemScoring
  • AssessmentRiskMatrix
  • RiskMatrixItem
Integration
  • Ssp (System Security Plans)
  • SspAssessmentEvent
  • SspSection
  • Wisp (Wireless Security)

Assessment Features

Template Management
  • Customizable question templates
  • Multiple choice and text responses
  • RACI framework integration
  • Vendor tool associations
  • Global and local template sharing
Automated Scoring
  • Configurable scoring algorithms
  • Risk matrix calculations
  • Color-coded risk levels
  • SPRS (Supplier Performance Risk System)
  • Custom scoring instructions

Risk Management Framework

Comprehensive risk management with risk registers, POAM (Plan of Action and Milestones), and mitigation tracking.

Risk Management Models

Model Description Key Features
RiskManagementFramework Framework definitions (NIST, ISO, etc.) Global/client-specific, notes
RiskRegisterList Risk register containers Assessment event linking
RiskRegisterItem Individual risk entries Risk details, implementation statements
PlanOfActionAndMilestone POAM tracking for risk mitigation Milestone management, deadlines
NoActionItem Risks requiring no action Decided action reasoning
Risk Workflow
  1. Assessment identifies risks
  2. Risks added to register
  3. Risk analysis and scoring
  4. POAM created for mitigation
  5. Milestone tracking and updates
  6. Risk closure or no-action decision

Service Layer

The service layer contains business logic and complex operations, keeping controllers thin and promoting code reuse.

Core Services
  • AssessmentEventService - Assessment processing
  • AssessmentTemplateService - Template management
  • PolicyService - Policy operations
  • PolicyDocumentService - Document handling
  • CompanyService - Company operations
  • PermissionService - Authorization logic
Integration Services
  • Auth0Service - Authentication integration
  • StripeService - Payment processing
  • Pax8Service - Partner integration
  • EmailService - Email operations
  • NotificationService - Notifications
  • ExportToWordService - Document export

External Integrations

The platform integrates with 20+ external services for comprehensive compliance management.

Category Services Integration Type Key Features
RMM Platforms ConnectWise, N-Central, Ninja, Auvik API Keys, Asset Sync Asset management, client import
Security Tools Huntress, CyberCNS, Breach Secure Now API Integration Security data, vulnerability tracking
Cloud Storage MS Graph, SharePoint, Google Drive OAuth, File APIs Evidence storage, document management
Communication MS Teams, Slack Webhooks, Bot APIs Notifications, collaboration
Payment Stripe, Pax8 Webhooks, API Billing, subscription management

Database Migrations

The database schema is managed through Laravel migrations with extensive history and complex relationships.

# Key Migration Categories

## Core System (2022-2023)
- User and authentication system
- Company and client management  
- Role-based permissions
- Policy and template foundations

## Assessment System (2023)
- Assessment templates and events
- Scoring and risk matrix systems
- SPRS reporting capabilities

## Advanced Features (2025-2026)
- Task management and milestones
- Trust center and public features
- Advanced integrations
- External API usage tracking
Migration Count: 200+ migrations tracking the evolution of the platform since December 2022.

Model Relationships

Complex relationship mapping between core entities in the system.

Core Entity Relationships

Company
├── hasMany: Users, Clients, CompanyExtraProducts
├── hasOne: BetaTester, TrustCenterDetails
└── hasMany: ClientFeatureToggles

User
├── belongsTo: Company, Role, Contact
├── hasOne: UserPermission
├── hasMany: Pax8Provision
└── belongsToMany: Ssp (auditors)

Client  
├── belongsTo: Company
├── hasMany: Users, Contacts, Policies, Assessments
├── hasOne: ClientFeatureToggle
└── hasMany: ApiKeys, ConnectorClientMappings

Policy
├── belongsTo: Client, Category, Contact (owner)
├── hasMany: PolicyDocuments, PolicyReviews
├── belongsToMany: RiskManagementFrameworks
└── hasMany: PolicyAdoptionQuestions

AssessmentEvent
├── belongsTo: Client, AssessmentTemplate
├── hasMany: AssessmentEventQuestions
├── hasOne: AssessmentRiskMatrix
└── belongsToMany: RiskRegisterLists