Skip to main content

Architecture & Platform

Detailed technical architecture of the Profile PS3 erosion control management system.

Technology Stack​

Core Platform​

  • Framework: Laravel 12.x (latest major release)
  • PHP: 8.3+ with modern features
  • Starter Kit: Larament by CodeWithDennis
  • Admin Framework: Filament 4.1+ with SPA mode
  • Frontend: Inertia.js + Vue 3.2.0
  • Database: MySQL 8.0+ / MariaDB 10.3+ (SQLite for development)
  • File Storage: AWS S3 via Laravel Flysystem
  • Email: Mailgun via Symfony Mailer
  • PDF Generation: DomPDF 3.1+

PHP Extensions Required​

  • OpenSSL
  • PDO (MySQL/SQLite)
  • Mbstring
  • Tokenizer
  • XML
  • Ctype
  • JSON
  • BCMath (for precise calculations)
  • Fileinfo
  • GD (image manipulation)

Application Architecture​

Dual Panel System​

Profile PS3 uses Filament's multi-panel architecture with two distinct interfaces:

Admin Panel (/admin)​

  • Full administrative control
  • CRUD operations for all resources
  • User management and role assignment
  • Material database management
  • Geographic data management
  • BDO export configuration
  • System settings

Access Control: Administrators and Super Admins only

App Panel (/app)​

  • User-facing project management interface
  • Project CRUD with slopes, channels, soil tests
  • Application Rate Calculator
  • ProGanics BSM Calculator
  • Personal profile management
  • Project attachments and documentation

Access Control: All approved registered users

Authentication & Authorization​

Multi-Factor Authentication (MFA):

  • App-based authenticator support (TOTP)
  • Recovery codes for account recovery
  • Per-user MFA enrollment

Role-Based Access Control:

  • Powered by Spatie Laravel Permission
  • Integrated with Filament via althinect/filament-spatie-roles-permissions
  • Roles: Super Admin, Admin, Manager, User
  • Fine-grained permissions for resources and actions

Account Approval Workflow:

  • New user registration creates pending status
  • Admin approval required before access
  • States: pending, approved, denied
  • Email notifications on approval/denial

Database Schema Overview​

40+ Database Tables organized into logical groups:

User Management:

  • users — Application users with company details
  • user_notifcation_regions — Regional notification preferences
  • model_has_roles, model_has_permissions — Spatie permission tables

Project Management:

  • projects — Main project records with location
  • slopes — Slope protection calculations
  • channels — Channel protection calculations
  • soil_tests — Soil analysis data
  • attachments — Project documentation files
  • project_types, project_stages, project_type_energies — Taxonomies

Material Databases:

  • ecbs — Erosion Control Blanket specifications
  • hecps — Hydraulically Applied Erosion Control Product data
  • trms — Turf Reinforcement Mat specifications
  • Coverage and application rate tables

Geographic Data:

  • countries, states, cities — Location hierarchy
  • sales_regions — Territory management

Calculator Systems:

  • application_calculators — Application rate calculations
  • proganics_calculators — ProGanics BSM calculations
  • Session-based calculation storage

Export System:

  • bdo_exports — Export history
  • bdo_export_checkpoints — Incremental export tracking
  • Supports multiple entity types (projects, users, materials)

Key Architectural Patterns​

Global Scopes​

UserProjectScope (Applied to Project model):

// Automatically filters projects by current user
// Except for admins who see all projects
if (!auth()->user()->hasRole(['super-admin', 'admin'])) {
    $builder->where('userId', auth()->id());
}

Strict Models​

Uses nunomaduro/essentials for enhanced Laravel defaults:

  • Strict model property access (prevents typos)
  • Auto-eager loading prevention (N+1 query detection)
  • Immutable dates (prevents accidental modification)

Service Providers​

Key Providers:

  • AdminPanelProvider — Admin panel configuration
  • AppPanelProvider — User panel configuration
  • AppServiceProvider — Application bootstrap
  • FilamentSpatieRolesPermissionsServiceProvider — RBAC integration

File Storage Architecture​

AWS S3 Configuration:

AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=profileps3-attachments
AWS_USE_PATH_STYLE_ENDPOINT=false

Local Development Fallback:

FILESYSTEM_DISK=local

Usage:

  • Project attachments (PDFs, images, documents)
  • Exported reports and calculations
  • Material specification sheets

Email Architecture​

Mailgun Integration:

MAIL_MAILER=mailgun
MAILGUN_DOMAIN=mg.profileps3.com
MAILGUN_SECRET=key-xxxxxxxxxxxxxxxx
MAILGUN_ENDPOINT=api.mailgun.net
[email protected]
MAIL_FROM_NAME="Profile PS3"

Email Notifications:

  • Account approval/denial
  • Regional sales notifications (new projects in territory)
  • Password reset
  • MFA recovery codes

API Architecture​

Internal REST API (for AJAX requests):

  • Calculator endpoints for real-time calculations
  • Material lookup endpoints
  • Geographic data endpoints (cities by state, etc.)
  • File upload endpoints

External Integration:

  • BDO Export API (outbound data synchronization)
  • AWS S3 API (file storage)
  • Mailgun API (email delivery)

Performance Optimizations​

Database:

  • Indexed foreign keys for fast lookups
  • Eager loading relationships to prevent N+1 queries
  • Query result caching for geographic and material data

Caching:

CACHE_STORE=redis  # Production
CACHE_STORE=file   # Development

Session Management:

SESSION_DRIVER=redis  # Production
SESSION_DRIVER=file   # Development

Asset Compilation:

  • Vite for modern frontend builds
  • CSS/JS minification in production
  • Asset versioning for cache busting

Testing Architecture​

Testing Framework: Pest (modern PHPUnit alternative)

Test Coverage:

  • 100+ feature tests
  • Model factories for all major entities
  • Database seeders for development data
  • Feature tests for calculators
  • Policy tests for authorization

Test Database:

DB_CONNECTION=sqlite  # In-memory for fast tests

Security Features​

Password Hashing: Bcrypt with cost factor 12

MFA: TOTP-based app authenticator (Google Authenticator, Authy, 1Password)

CSRF Protection: Laravel's built-in CSRF token validation

SQL Injection Prevention: Eloquent ORM with parameter binding

XSS Prevention: Blade template auto-escaping

File Upload Validation: MIME type checking, file size limits

Rate Limiting: API rate limiting for calculator endpoints

Impersonation Auditing: Admin user impersonation tracked in logs

Development Environment​

Recommended Setup:

  • Laravel Herd (macOS/Windows)
  • PHP 8.3 via Homebrew (macOS) or Laravel Herd
  • MySQL 8.0 via Homebrew or Docker
  • Redis via Homebrew or Docker
  • Node.js 20+ for Vite builds
  • VS Code with PHP Intelephense extension

Alternative Setup:

  • Laravel Sail (Docker-based development)
  • All dependencies containerized
  • Cross-platform compatibility

Deployment Architecture​

Production Environment:

  • VPS or shared hosting with PHP 8.3+
  • MySQL 8.0+ database
  • Redis for caching and sessions
  • AWS S3 for file storage
  • Mailgun for email delivery
  • SSL/TLS certificates (Let's Encrypt)

Deployment Process:

  1. Git push to production branch
  2. SSH to server
  3. git pull origin production
  4. composer install --optimize-autoloader --no-dev
  5. npm ci && npm run build
  6. php artisan migrate --force
  7. php artisan config:cache
  8. php artisan route:cache
  9. php artisan view:cache
  10. php artisan filament:optimize

Environment Configuration:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://profileps3.com
LOG_CHANNEL=daily
LOG_LEVEL=warning

Monitoring & Logging​

Logging:

  • Daily log rotation
  • Separate channels for different log types
  • Error tracking with context

Monitoring:

  • Server resource monitoring (CPU, memory, disk)
  • Database query performance
  • Application error rates
  • User activity metrics

Future Architecture Considerations​

Potential Enhancements:

  • API versioning for external integrations
  • GraphQL API for mobile applications
  • WebSocket integration for real-time notifications
  • Elasticsearch for advanced search capabilities
  • Redis queue for background job processing
  • Multi-tenancy for white-label deployments