Multi-Tenant Store Blueprint (Modulith)

This blueprint defines the module dependency graph, event flows, and directory layout for a multi-tenant e-commerce application built on zmodu.

Reference implementations:

• examples/tenant-mgmt/: Platform tenant, user, and subscription modules.
• examples/tenant-shop/: Full commerce workflow (catalog, inventory, cart, order, payment, and transactional outbox).

1. Architecture Overview

2. Module Dependency Graph

2.1 Synchronous Dependencies (info.dependencies)

Arrows point from dependency to dependent (A --> B means B declares A in info.dependencies):

flowchart TB
  subgraph platform["Platform"]
    tenant["tenant"]
    user["user"]
  end

  subgraph catalog["Catalog & Inventory"]
    product["product"]
    inventory["inventory"]
  end

  subgraph commerce["Commerce"]
    cart["cart"]
    order["order"]
    payment["payment"]
  end

  subgraph bff["BFF (Stateless)"]
    shop_bff["shop_bff"]
    admin_bff["admin_bff"]
  end

  tenant --> user
  tenant --> product
  tenant --> inventory
  product --> inventory
  tenant --> cart
  product --> cart
  inventory --> cart
  tenant --> order
  user --> order
  product --> order
  inventory --> order
  cart --> order
  tenant --> payment
  order --> payment

  product --> shop_bff
  cart --> shop_bff
  order --> shop_bff
  payment --> shop_bff
  user --> shop_bff

  tenant --> admin_bff
  product --> admin_bff
  inventory --> admin_bff
  order --> admin_bff
  user --> admin_bff

2.2 Module Declarations

2.3 Asynchronous Events

All event payloads include tenant_id and an idempotency key so consumers can safely retry.

3. Request Middleware Pipeline

HTTP Request
  -> recover / requestId / rateLimit
  -> catalog JWT authentication (extracts `user_id` from `sub`, `tenant_id` from `aud`)
  -> moduleGate + permissionGateWith(.rbac)
  -> shop_bff | admin_bff | domain api handler
  -> service (passes `tenant_id` explicitly)
  -> persistence (`WHERE tenant_id = ?`)

4. Directory Layout

tenant-shop/
├── build.zig
├── build.zig.zon
├── init.sql
└── src/
    ├── main.zig
    ├── config.zig
    ├── foundation/
    │   ├── db.zig
    │   ├── redis.zig
    │   ├── mq.zig
    │   └── outbox.zig
    ├── business/
    │   └── enums.zig
    └── modules/
        ├── tenant/       # module.zig, model.zig, persistence.zig, service.zig, api.zig, root.zig
        ├── user/
        ├── product/
        ├── inventory/
        ├── cart/
        ├── order/
        ├── payment/
        ├── shop_bff/     # module.zig, service.zig, api.zig, root.zig (no persistence.zig)
        └── admin_bff/    # module.zig, service.zig, api.zig, root.zig (no persistence.zig)

5. Bootstrap Sequence (src/main.zig)

var b = zmodu.builder(allocator, io);
defer b.deinit();
var app = try b.withName("tenant-shop")
    .build(.{
        tenant.Module,
        user.Module,
        product.Module,
        inventory.Module,
        cart.Module,
        order.Module,
        payment.Module,
        shop_bff.Module,
        admin_bff.Module,
    });
defer app.deinit();

try app.start();
defer app.stop();

6. Database Schema Conventions