Multi-Tenant SaaS Architecture, DDD & Filament v5
Production multi-tenancy, the parent_id anchor model, Filament admin, and 17 bug ledger
Engineered directly from production SaaS platforms. Explore the parent_id anchor multi-tenancy model; implement TenantScoped and BranchScoped traits; create tiered subscription billing with JSON feature flags; configure Filament v5 multi-panel administration (Owner, Staff, Admin); and study the definitive 17 Production Bug & Fix Ledger detailing real-world gotchas and architectural patches.
Course Prerequisites
- PHP 8.4 + Laravel 13 Fundamentals & Classical Blade MVC or equivalent professional Laravel experience.
Part of Academy Track:
What You Will Master
Curriculum Modules (5 Modules)
Explore the structured module breakdown, lesson outcomes, and practical lab exercises.
Module 1: Domain-Driven SaaS Architecture
6 Lessons • ~9.5 Study Hours (0.95 CEUs)Welcome to Module 1: Domain-Driven SaaS Architecture. In this section of the curriculum, learners dive deep into foundational and advanced principles designed for production application. This module covers: Evaluate monoliths, domain-driven modular monoliths, and microservices for SaaS backends. Understand why modular DDD is the optimal architectural fit for multi-tenant systems.; Master the universal domain-driven directory layout for multi-tenant SaaS backends. Understand the strict role of app/Common, app/Api, and domain modules.; Establish firm boundaries between app/Common and domain modules. Master communication rules, event-driven integration, and anti-corruption layers..
Architectural Decision Framework: Monolith vs Modular DDD vs Microservices
Evaluate monoliths, domain-driven modular monoliths, and microservices for SaaS backends. Understand why modular DDD is the optimal architectural fit for multi-tenant systems.
Universal SaaS DDD Directory Layout: app/Common, app/Api, and app/{Domain}
Master the universal domain-driven directory layout for multi-tenant SaaS backends. Understand the strict role of app/Common, app/Api, and domain modules.
Bounded Contexts & Module Isolation: Defining Common vs Domain Responsibilities
Establish firm boundaries between app/Common and domain modules. Master communication rules, event-driven integration, and anti-corruption layers.
Modular Migrations & Registration: loadMigrationsFrom() in AppServiceProvider
Configure dynamic migration loading and modular service registration. Eliminate flat migration clutter by scoping schemas cleanly to each domain.
Global Utilities Pattern: utils.php, global_values.php and Currency Helpers
Implement clean functional helpers in utils.php and global_values.php. Learn safe composer autoloading and currency formatting across multi-currency tenants.
Custom PSR-4 Namespacing inside Domain Modules
Configure PSR-4 autoloading rules for domain modules and path packages. Ensure seamless class resolution across multi-app architectures.
Module 2: Multi-Tenancy Architecture: The parent_id Model
7 Lessons • ~12.2 Study Hours (1.22 CEUs)Welcome to Module 2: Multi-Tenancy Architecture: The parent_id Model. In this section of the curriculum, learners dive deep into foundational and advanced principles designed for production application. This module covers: Deep dive into multi-tenancy models: shared database with discriminator columns, multi-schema PostgreSQL, and multi-database isolation. Understand operational tradeoffs.; Analyze the parent_id architectural pattern. Understand why anchoring tenant ownership to the account owner (users.id) creates an elegant, unified tenancy model.; Build the production-grade TenantScoped trait. Automatically inject global query scopes and populate parent_id on model creation..
Multi-Tenancy Architecture Patterns: Column vs Separate Schema vs Separate DB
Deep dive into multi-tenancy models: shared database with discriminator columns, multi-schema PostgreSQL, and multi-database isolation. Understand operational tradeoffs.
The parent_id Anchor: Why parent_id -> users.id Dominates Multi-Tenant Architecture
Analyze the parent_id architectural pattern. Understand why anchoring tenant ownership to the account owner (users.id) creates an elegant, unified tenancy model.
Building the TenantScoped Trait: Auto-Assignment & Global Scope Injection
Build the production-grade TenantScoped trait. Automatically inject global query scopes and populate parent_id on model creation.
Multi-Location Isolation: The BranchScoped Trait & Outlet Resolution
Architect multi-location tenant support. Implement the BranchScoped trait for physical branches, outlets, and medical centers under a unified parent tenant.
The Unified User Model: Types (Owner, Staff, Customer, Contact) and Tenancy Guards
Engineer a unified User entity supporting multiple persona types: owner, staff, customer, and contact. Implement Filament tenancy guards and access policies.
Organization & Branch Entities: Multi-Currency, API Keys, and Status Enums
Design the Organization and Branch domain models. Configure tenant metadata, cryptographic API keys (HMAC), currencies, and operating status enums.
Filament Multi-Tenancy Integration: HasTenants, ownershipRelationship, and canAccessTenant
Configure Filament v5 native multi-tenancy. Master HasTenants, panel tenant registration, ownershipRelationship, and security access gates.
Module 3: Core Platform Entities
9 Lessons • ~13.6 Study Hours (1.36 CEUs)Welcome to Module 3: Core Platform Entities. In this section of the curriculum, learners dive deep into foundational and advanced principles designed for production application. This module covers: Design subscription tiers with JSON feature flags and numeric limit caps. Implement tenant plan middleware and runtime quota enforcement services.; Build high-throughput Pay-As-You-Go (PAYG) meter billing. Leverage Redis atomic decrements, double-entry ledger transactions, and daily deduction jobs.; Integrate global and regional payment gateways. Structure CheckoutController, webhook idempotency, signature verification, and ledger reconciliation..
Subscription Plan Architecture: Feature Flags & Numeric Limit Caps
Design subscription tiers with JSON feature flags and numeric limit caps. Implement tenant plan middleware and runtime quota enforcement services.
Pay-As-You-Go (PAYG) Billing: Redis Wallets, Daily Deductions & Ledger Transactions
Build high-throughput Pay-As-You-Go (PAYG) meter billing. Leverage Redis atomic decrements, double-entry ledger transactions, and daily deduction jobs.
Multi-Gateway Payments: CheckoutController, Stripe, PayPal & Local Gateways
Integrate global and regional payment gateways. Structure CheckoutController, webhook idempotency, signature verification, and ledger reconciliation.
Multi-Tenant RBAC: Spatie Permissions with Teams Bound to parent_id
Configure Spatie Permissions for multi-tenant teams. Bind team_foreign_key to parent_id, enabling granular role assignment isolated per organization.
Tenant-Scoped Audit Logging: Custom Activity Models & Event Listeners
Implement HIPAA/SOC2 compliant audit logging using Spatie Activitylog. Build custom tenant-scoped Activity models and prevent signature mismatch errors.
Dynamic Extensibility: Definition-Based Custom Attributes (EAV) & JSON Storage
Build a hybrid Entity-Attribute-Value (EAV) system. Allow tenants to define custom fields dynamically without altering database schemas.
Multi-Channel Notification Matrix: Per-User Channel JSON Preferences
Build a multi-channel notification engine (email, SMS, in-app database, push). Allow users and tenants to configure granular delivery channel preferences.
System UIDs: NanoID/UUID Generation & UI Sanitization Rules
Design immutable public system identifiers (UIDs). Prevent sequential ID harvesting attacks and establish strict UI sanitization conventions.
Enterprise Data Retention: is_deleted + deleted_at and the Forbidden Hard Delete
Master enterprise data retention policies. Implement hybrid soft deletes (is_deleted boolean + deleted_at timestamp) and enforce the forbidden hard delete rule.
Module 4: Filament v5 Admin Panel Engineering
10 Lessons • ~13.9 Study Hours (1.39 CEUs)Welcome to Module 4: Filament v5 Admin Panel Engineering. In this section of the curriculum, learners dive deep into foundational and advanced principles designed for production application. This module covers: Master the architectural foundations of Filament v5. Understand how Panel Providers, the unified Schemas API, Actions, and Widgets work together.; Configure multi-panel separation in Filament v5. Build an isolated SuperAdmin panel for platform governance and a multi-tenant Admin panel for tenant staff.; Engineer robust Filament v5 Resources. Master getEloquentQuery() query optimization, schema definitions, and page handler lifecycles..
Filament v5 Architecture: Panel Providers, Schemas, Actions, and Widgets
Master the architectural foundations of Filament v5. Understand how Panel Providers, the unified Schemas API, Actions, and Widgets work together.
Multi-Panel Architecture: Isolating Tenant Admin from Superadmin Panels
Configure multi-panel separation in Filament v5. Build an isolated SuperAdmin panel for platform governance and a multi-tenant Admin panel for tenant staff.
Filament v5 Resource Engineering: getEloquentQuery(), Schemas, and Page Handlers
Engineer robust Filament v5 Resources. Master getEloquentQuery() query optimization, schema definitions, and page handler lifecycles.
Filament Shield: Automated Policy Generation, Permission Sync, and Resource Gates
Deploy bezhansalleh/filament-shield for automated RBAC. Generate resource policies, sync permissions with Spatie, and secure UI actions.
The Filament v5 Schema System: Layout Components, Fields, and Migrating from Forms
Master the Filament v5 Schemas architecture. Learn why layout classes moved to FilamentSchemasComponents and how to build responsive form layouts.
Advanced Filament Tables: Computed Columns, Multi-Tenant Filters, and Bulk Actions
Build high-performance Filament tables. Implement computed columns, badge statuses, multi-tenant relational filters, and batch actions.
Interactive Filament Actions: Header Actions, Form Modals, and Action Execution
Create custom interactive Filament actions. Build confirmation modals, parameter collection forms, and transactional execution pipelines.
Dashboard Metrics & Widgets: StatsOverview, Real-time Charts, and Aggregations
Design high-impact analytics dashboards. Build StatsOverview widgets, trend charts, and prevent strict SQL grouping bugs in aggregation queries.
Panel Navigation: Heroicons v2, Groups, and UnitEnum Strict Typing
Configure panel sidebar navigation. Enforce UnitEnum|string|null strict typing and integrate Heroicons v2 seamlessly.
Tenant Impersonation Architecture: Session Bypassing vs Auth Invalidation Traps
Architect customer support tenant impersonation. Avoid Auth::login() session destruction traps using session-based impersonation tokens.
Module 5: The 17 Production Gotchas & Bug Ledger
17 Lessons • ~23.2 Study Hours (2.32 CEUs)Welcome to Module 5: The 17 Production Gotchas & Bug Ledger. In this section of the curriculum, learners dive deep into foundational and advanced principles designed for production application. This module covers: Solve the classic empty dropdown bug where global scopes automatically applied to User/Customer models strip out valid records during form rendering.; Resolve fatal Class Not Found exceptions caused by blurring the boundaries between Filament\Actions and Filament\Tables\Actions.; Fix Undefined type errors caused by layout components transitioning from Filament\Forms\Components to Filament\Schemas\Components..
Gotcha #1: Global Scope Interference in Filament Select Options & Relation Managers
Solve the classic empty dropdown bug where global scopes automatically applied to User/Customer models strip out valid records during form rendering.
Gotcha #2: Filament v5 Action Namespace Collisions (FilamentActions vs TablesActions)
Resolve fatal Class Not Found exceptions caused by blurring the boundaries between FilamentActions and FilamentTablesActions.
Gotcha #3: Layout Component Namespaces (FilamentSchemasComponents vs Forms)
Fix Undefined type errors caused by layout components transitioning from FilamentFormsComponents to FilamentSchemasComponents.
Gotcha #4: Navigation Property Strictness: UnitEnum|string|null Type Constraints
Diagnose and repair PHP FatalError: Type of Resource::$navigationGroup must be UnitEnum|string|null caused by strict typing violations.
Gotcha #5: IDE False Positives on Model Traits: @phpstan-require-extends Fix
Eliminate IDE and Larastan false warnings on TenantScoped traits using the @phpstan-require-extends annotation.
Gotcha #6: Tenant Ownership Relationship Naming: Why ownershipRelationship Must Be 'parent'
Diagnose The model does not have a relationship named [user] errors by aligning Filament tenancy configuration with the parent_id anchor.
Gotcha #7: Spatie Activitylog Return Type Signature Mismatch on Model Overrides
Fix Declaration of Activity::subject() must be compatible with Spatie return type signature mismatch errors under PHP 8.2+.
Gotcha #8: Deprecated form() Method vs v5 schema() Method Signatures
Resolve Undefined type 'FilamentFormsForm' errors by migrating from legacy form() methods to Filament v5's schema() method.
Gotcha #9: Strict SQL Mode only_full_group_by Violations in Analytics Aggregations
Resolve SQLSTATE[42000] only_full_group_by access violations in analytics queries without disabling MySQL strict mode.
Gotcha #10: Leaking Internal Keys: Hiding parent_id and System Tokens from UI Schemas
Prevent sensitive relational anchors and tokens from leaking into Filament forms and tables during automated resource scaffolding.
Gotcha #11: Laravel Dusk ChromeDriver Binary Drift in Automated Browser Testing
Fix session not created: ChromeDriver version mismatch errors during automated end-to-end browser testing with Laravel Dusk.
Gotcha #12: Hallucinated Vendor Namespaces & Accidental Livewire Method Redeclarations
Prevent fatal Trait not found and Cannot redeclare mount() errors during rapid feature development and refactoring.
Gotcha #13: Overcoming Deep CSS Specificity in Filament-Wrapped Blade Layouts
Resolve styling fights where Tailwind utility classes fail to center elements inside Filament-wrapped Blade checkout pages.
Gotcha #14: Payment Gateway Credential Misconfiguration & Modal Redirect Traps
Fix payment gateway popup failures where malformed API keys or unprevented form submissions trigger blank fallback redirect screens.
Gotcha #15: Resource Naming Collisions: Disambiguating Tenant vs System Roles
Prevent UI confusion when both Tenant Roles and System Roles share the same underlying model by explicitly overriding model labels.
Gotcha #16: Displaying Raw Foreign Keys vs Eager-Loaded Relational Attributes
Replace raw numeric foreign keys (customer_id: 42) with descriptive eager-loaded relationship attributes (customer.name) on tables and views.
Gotcha #17: Silent Zero-Value Charts: Debugging Inaccurate Column Aggregations
Diagnose silent chart flatlining where revenue plots at 0 despite completed database transactions due to column mismatches or missing status filters.
Modern PHP, Laravel & SaaS Progression
Continue advancing through the sequential curriculum stages of this academy track: