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:
  - Codex
  - codex
---

# Modular SAAS Architecture
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.


## 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.


<!-- dual-compat-start -->
## 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.
<!-- dual-compat-end -->
## 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

```php
// 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, 'trial_days' => 14],
];
```

## Module Registry & Access Control

```php
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(string $moduleCode): void {
    if (!isLoggedIn()) { header('Location: ./sign-in.php'); exit(); }
    $stmt = $this->db->prepare('SELECT is_enabled FROM tbl_franchise_modules WHERE franchise_id = ? AND module_code = ?');
    $stmt->execute([$_SESSION['franchise_id'], $moduleCode]);
    if (!$stmt->fetchColumn()) {
        header('Location: ./module-not-available.php?module=' . urlencode($moduleCode)); exit();
    }
}

// Non-blocking check — for conditional UI
function hasModuleAccess(string $moduleCode): bool {
    if (!isLoggedIn()) return false;
    $stmt = $this->db->prepare('SELECT is_enabled FROM tbl_franchise_modules WHERE franchise_id = ? AND module_code = ?');
    $stmt->execute([$_SESSION['franchise_id'], $moduleCode]);
    return (bool) $stmt->fetchColumn();
}
```

## Page-Level Protection

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

## Module Independence Patterns

### Pattern 1: Optional Dependencies

```php
// 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

```php
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

```php
// 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

```sql
-- 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                  BIGINT AUTO_INCREMENT PRIMARY KEY,
    franchise_id        BIGINT NOT NULL,
    restaurant_table_id BIGINT NULL           -- Nullable! No FK to optional module table
);
```

## Dynamic Navigation

```php
// 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)

```php
// 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 |