modular-saas-architecture

name	modular-saas-architecture
description	Use when designing tenant-selectable SaaS modules, dependency contracts, module toggles, lifecycle hooks, or safe enable and disable behaviour.
metadata	{"portable":true,"compatible_with":["claude-code","codex"]}

Modular SAAS Architecture

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, [phone].

Required Inputs

Input	Required	Use
Tenant, product, and lifecycle scope	yes	Bound the SaaS decision
Current architecture, plans, policies, and constraints	yes	Preserve enforceable behaviour
Production data or verified evidence	conditional	Validate thresholds and migrations

Capability and permission contract

Default to read-only analysis. Change configuration, billing, identity, tenant data, infrastructure, or customer communications only with explicit authority, least-privilege credentials, tenant scope, rollback, and auditable approval. Never expose secrets or cross tenant boundaries.

Degraded mode

If production access, policy, telemetry, or authoritative records are unavailable, produce a labelled design or dry-run plan. Do not claim deployment, reconciliation, deletion, delivery, or measured outcomes; list missing evidence and verification.

Decision rules

Condition	Action	Stop condition
Tenant isolation, money, identity, or deletion is affected	Require approval and rollback evidence	Scope or authority is ambiguous
Evidence supports a reversible change	Stage, test, and record it	Acceptance checks fail
Only partial context is available	Return assumptions and validation	A production claim cannot be verified

Domain Anti-Patterns

• Applying one tenant's policy or data to another. Fix: enforce tenant scope at every boundary.
• Mutating production from an advisory request. Fix: remain read-only until authority is explicit.
• Inventing limits, prices, metrics, or compliance claims. Fix: use authoritative records or mark them unresolved.
• Shipping without rollback and audit evidence. Fix: stage and retain before/after proof.
• Treating a missing dependency as successful. Fix: name the blocked verification.

Use When

• Build SAAS platforms with pluggable business modules (Advanced Inventory, Restaurant, Pharmacy, etc.) that can be enabled/disabled per tenant without breaking the system. Use when designing modular SAAS features, implementing module toggles...

Evidence Produced

Category	Artifact	Format	Example
Correctness	Module gate decision record	Markdown doc per skill-composition-standards/references/adr-template.md covering pluggable-module choices and per-tenant enablement	docs/saas/module-gate-adr.md

References

• Use the references/ directory for deep detail after reading the core workflow below.
• Use the examples/ directory for concrete patterns when implementation shape matters.
• Use the documentation/ directory for supporting implementation detail or migration notes.

Load Alongside

• world-class-engineering for release gates and output standards.
• saas-erp-system-design when modules encode significant business workflows.
• database-design-engineering for schema ownership, tenancy, and migration safety.
• vibe-security-skill for security review.

Overview

Architecture pattern for building SaaS platforms where business modules (Advanced Inventory, Restaurant, Pharmacy, Retail, etc.) can be independently enabled, disabled, or added without affecting other parts of the system.

Core Principles:

• Module Independence: Each module is self-contained with minimal dependencies
• Graceful Degradation: Disabling a module doesn't break dependent features
• Per-Tenant Control: Each tenant can enable only the modules they need
• Zero Breaking Changes: Adding/removing modules preserves existing functionality

Security Baseline (Required): Always load and apply the Vibe Security Skill for any web app, API, or module implementation work.

📖 See references/implementation.md for full lifecycle code, testing patterns, and anti-patterns.

When to Use

✅ Multi-tenant SaaS platforms with diverse customer needs ✅ Systems serving different industries (retail, healthcare, hospitality) ✅ Platforms with optional premium features ❌ Single-tenant applications or tightly coupled monolithic systems

Module Architecture Pattern

┌─────────────────────────────────────────────────┐
│                CORE SYSTEM                       │
│  Authentication, Multi-tenant, Users, Billing,   │
│  Audit Logs, Module Registry & Feature Flags     │
└───────────────────┬─────────────────────────────┘
                    │
    ┌───────────────┼───────────────┐
    ▼               ▼               ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│ 🏪 Retail│  │🍽️ Restaurant│  │💊 Pharmacy│
│ POS Sales│  │Table Mgmt │  │Rx Mgmt   │
│ Inventory│  │Orders     │  │Drug DB   │
│ Invoicing│  │Kitchen    │  │Scripts   │
└──────────┘  └──────────┘  └──────────┘

Per-Tenant Config:
  Tenant A: Retail + Adv. Inventory (enabled)
  Tenant B: Restaurant + Hospitality (enabled)
  Tenant C: Pharmacy only (enabled)

Module Anatomy

modules/
└── advanced-inventory/
    ├── module.config.php    # Module metadata, features, permissions, menu
    ├── permissions.php
    ├── routes.php
    ├── database/
    │   └── schema.sql       # Module tables (all franchise-scoped)
    ├── services/            # Business logic
    ├── models/
    └── tests/

Module Configuration

// modules/advanced-inventory/module.config.php
return [
    'module_code' => 'ADV_INV',
    'name'        => 'Advanced Inventory',
    'description' => 'Multi-location inventory with UOM conversions and transfers',
    'version'     => '1.0.0',
    'requires'    => [],           // Empty = no dependencies
    'features'    => ['stock_items', 'uom_conversions', 'stock_transfers'],
    'permissions' => ['VIEW_INVENTORY', 'MANAGE_STOCK', 'APPROVE_TRANSFERS'],
    'tables'      => ['tbl_stock_items', 'tbl_stock_item_uoms', 'tbl_stock_transfers'],
    'menu'        => [
        ['label' => 'Inventory', 'icon' => 'bi-boxes', 'items' => [
            ['label' => 'Stock Items', 'url' => '/stock-items-catalog.php'],
            ['label' => 'UOM Conversions', 'url' => '/advanced-inventory-uom.php'],
            ['label' => 'Stock Transfers', 'url' => '/stock-transfers.php'],
        ]]
    ],
    'pricing' => ['type' => 'addon', 'price_monthly' => 29.99,  => ],
];

Module Registry & Access Control

class ModuleRegistry {
    public function getEnabledModules(int $franchiseId): array {
        $stmt = $this->db->prepare('
            SELECT module_code, config FROM tbl_franchise_modules
            WHERE franchise_id = ? AND is_enabled = 1
        ');
        $stmt->execute([$franchiseId]);
        return $stmt->fetchAll(PDO::FETCH_ASSOC);
    }

    public function isModuleEnabled(int $franchiseId, string $moduleCode): bool {
        $stmt = $this->db->prepare('
            SELECT is_enabled FROM tbl_franchise_modules
            WHERE franchise_id = ? AND module_code = ?
        ');
        $stmt->execute([$franchiseId, $moduleCode]);
        return (bool) $stmt->fetchColumn();
    }
}

// Blocking check — redirects if module disabled
function requireModuleAccess():  {
     (!()) { (); (); }
     = ->db->();
    ->([[], ]);
     (!->()) {
        ( . ()); ();
    }
}


{
     (!())  ;
     = ->db->();
    ->([[], ]);
     () ->();
}

Page-Level Protection

// On every module page — at the top, before any output
requireModuleAccess('ADV_INV');
requirePermissionGlobal('VIEW_INVENTORY');

Module Independence Patterns

Pattern 1: Optional Dependencies

// Check before using an optional module
class OrderService {
    public function createOrder(array $data) {
        $order = $this->saveOrder($data);
        // Use Advanced Inventory if enabled, else fallback
        if (hasModuleAccess('ADV_INV')) {
            (new AdvancedInventoryService())->updateInventory($order);
        } else {
            $this->updateBasicStock($order);
        }
    }
}

Pattern 2: Interface-Based Integration

interface InventoryProvider {
    public function checkStock(int $itemId, float $qty): bool;
    public function decrementStock(int $itemId, float $qty): void;
}

class InventoryFactory {
    public static function create(): InventoryProvider {
        return hasModuleAccess('ADV_INV')
            ? new AdvancedInventory()
            : new BasicInventory();
    }
}

Pattern 3: Event-Driven Communication

// Module A fires event — Module B optionally listens
class SalesModule {
    public function completeSale(Sale $sale) {
        $this->saveSale($sale);
        EventDispatcher::dispatch('sale.completed', ['sale' => $sale]);
    }
}

// modules/advanced-inventory/bootstrap.php
if (hasModuleAccess('ADV_INV')) {
    EventDispatcher::listen('sale.completed', function($data) {
        (new InventoryService())->decrementStock($data['sale']);
    });
}

Database Design

-- Module registry tables (core — always present)
CREATE TABLE tbl_modules (
    module_code VARCHAR(50) PRIMARY KEY,
    name        VARCHAR(255) NOT NULL,
    is_core     BOOLEAN DEFAULT 0
);

CREATE TABLE tbl_franchise_modules (
    id           BIGINT AUTO_INCREMENT PRIMARY KEY,
    franchise_id BIGINT NOT NULL,
    module_code  VARCHAR(50) NOT NULL,
    is_enabled   BOOLEAN DEFAULT 1,
    enabled_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    disabled_at  TIMESTAMP NULL,
    config       JSON,
    UNIQUE KEY (franchise_id, module_code),
    FOREIGN KEY (franchise_id) REFERENCES tbl_franchises(id),
    FOREIGN KEY (module_code)  REFERENCES tbl_modules(module_code)
);

-- Module tables: always include franchise_id for tenant isolation
CREATE TABLE tbl_stock_items (
    id           BIGINT AUTO_INCREMENT PRIMARY KEY,
    franchise_id BIGINT NOT NULL,
    name         VARCHAR(255) NOT NULL,
    FOREIGN KEY (franchise_id) REFERENCES tbl_franchises(id)
);

-- Cross-module FK: use NULL + application-level check (no hard FK to optional module)
CREATE TABLE tbl_sales (
    id                   AUTO_INCREMENT ,
    franchise_id         ,
    restaurant_table_id             
);

Dynamic Navigation

// Menu constraints: max 5 submenus, max 6 items each, Bootstrap Icons on all entries
<nav>
    <a href="/dashboard.php">Dashboard</a>
    <?php if (hasModuleAccess('RETAIL')): ?>
        <a href="/pos-sales.php">POS</a>
    <?php endif; ?>
    <?php if (hasModuleAccess('ADV_INV')): ?>
        <div class="dropdown"><a href="#">Inventory</a>
            <ul>
                <li><a href="/stock-items-catalog.php">Stock Items</a></li>
                <li><a href="/advanced-inventory-uom.php">UOM Conversions</a></li>
            </ul>
        </div>
    <?php endif; ?>
</nav>

Module Lifecycle (Summary)

// Enable: validate dependencies → run migrations → insert row → create trial subscription → audit log
// Disable: check dependents → UPDATE is_enabled=0 → cancel subscription → audit log
// NEVER delete module data on disable — user may re-enable
UPDATE tbl_franchise_modules SET is_enabled = 0, disabled_at = NOW() WHERE franchise_id = ? AND module_code = ?;

Best Practices

DO:

• Keep modules self-contained (own tables, own logic)
• Always include franchise_id in module tables
• Use hasModuleAccess() for optional dependencies
• Keep data when module is disabled (soft disable only)
• Use nullable FKs for cross-module references
• Define audit events for enable, disable, pricing, and role-sensitive actions

DON'T:

• Hard-code module dependencies (check at runtime)
• Delete data when module is disabled
• Share tables between modules
• Use hard FK constraints for optional modules
• Show disabled module navigation to users
• Fork module behavior per tenant in code when configuration or policy can express it

Implementation Checklist

• Module config file with metadata, features, permissions, menu
• requireModuleAccess() on every module page
• hasModuleAccess() for optional dependency checks
• Module registry in database (tbl_franchise_modules)
• Trial/subscription billing rows on enable
• Dynamic navigation using hasModuleAccess()
• Fallback logic when optional modules disabled
• Audit log for enable/disable events
• Isolation tests + integration tests

📖 See references/implementation.md for full lifecycle code, testing patterns, anti-patterns.

Quality Standards

A module is acceptable only when ownership, dependencies, activation state, migrations, tenant isolation, observability, failure containment, and disable behaviour can be tested independently.

Outputs

Artefact	Consumer	Acceptance condition
Module boundary and lifecycle specification	Platform and feature teams	Dependencies, tenant enablement states, data ownership, hooks, rollback path, and disable semantics are explicit and testable