README

Installable SaaS module pack for upMVC (bitshost/upmvc-saas-pack).

Adds multi-tenant SaaS capabilities to an upMVC application without turning the core framework into a SaaS-only project. This repo is a Composer library, not a runnable app.

Current release: v1.1.0 — Harvest — tenancy v1.0 + Harvest ops kernel (mail, notify primitives, audit, TOTP, Attention, i18n overlays).

Start here

Link	Role
BUILD_SAAS_APP	How to compose kernel + this pack + host
upMVC-SaaS	Thin starter host that `require`s this pack
upMVC-Payments-Pack	Optional payments (separate pack; ships `saas-kit.json`)
`docs/SAAS_NEXT.md`	Host CLI: `saas-next` doctor / init / scaffold

What This Pack Adds

Tenancy (v1.0)

API modules for auth, tenants, plans, and platform admin
Web shell modules for auth, platform admin, tenant app, tenant shop, and home
Tenant and plan-gate middleware (tenant, feature:*)
SaaS API base controller with tenant/user context
Migration 001_saas_layer.sql — plans, tenants, refresh_tokens

Harvest ops kernel

Shared factory libraries under BitsHost\UpmvcSaas\ (not CMMS domain):

Piece	Role
`Mail\MailGateway` + `Security\SecretBox`	Platform / plan-gated tenant SMTP, `.env` fallback, `email_log`, sealed passwords
`Notify\{NotifyRegistry,NotifyGate,Notify}`	Empty registry (apps register types); pause; instant fire + mutes
`Audit\AuditLog`	Append-only trail + impersonator
`Security\Totp`	Platform MFA helper
`Ops\{Attention,PlatformSettings,SchedulerHeartbeat}`	Attention board, flags, cron heartbeat
`I18n\Catalog`	File catalogs + DB overlays
Migration `002_saas_ops_layer.sql`	Tables for the above
API `PlatformOps`, `I18n`	Thin routes — apps override for domain Attention

Deliberately out of pack: domain notify catalogs, payments/billing, full PlatformAdmin UI tabs, AI translate.

See docs/09-harvest-ops.md for wiring, dual-unseal continuity, and the pack-vs-new-pack rule.

Intended Architecture

bitshost/upmvc                 → kernel
bitshost/upmvc-saas-pack       → this pack (tenancy + Harvest)
bitshost/upmvc-payments-pack   → optional payments
upMVC-SaaS / your product      → thin host: public/, .env, packages.php, domain modules

Install In An upMVC App

Requires upMVC ^2.4+ (prefer ^2.5 with current starter pins). Library-mode Application, module/migration paths, middleware factories.

composer require bitshost/upmvc-saas-pack

Then register the provider in the host app:

// src/Etc/packages.php
return [
    \BitsHost\UpmvcSaas\SaasServiceProvider::class,
];

The provider registers:

the pack module path
SaaS protected routes
tenant named middleware
feature:* middleware factory
migration path metadata (001 + 002)

Apply migrations with the host app’s migrate tool (kernel → pack → app order).

Local Development

Use Composer path repositories from the host app while developing locally:

{
  "repositories": [
    {
      "type": "path",
      "url": "../upMVC",
      "options": { "symlink": true }
    },
    {
      "type": "path",
      "url": "../upMVC-SaaS-Pack",
      "options": { "symlink": true }
    }
  ],
  "require": {
    "bitshost/upmvc": "^2.4",
    "bitshost/upmvc-saas-pack": "dev-master"
  },
  "minimum-stability": "dev",
  "prefer-stable": true
}

saas-next (host helper)

From a composed host app:

php vendor/bitshost/upmvc-saas-pack/bin/saas-next.php doctor
php vendor/bitshost/upmvc-saas-pack/bin/saas-next.php init
php vendor/bitshost/upmvc-saas-pack/bin/saas-next.php agent --goal "…"

Discovers other packs via each package’s saas-kit.json (payments included). See docs/SAAS_NEXT.md.

Agent / docs

Human docs: docs/ — especially 09-harvest-ops.md
Kernel agent JSON (when pack is installed): upMVC docs/agent/upmvc-saas-pack.json — do not duplicate a full agent pack here
Short agent pointer in this repo: AGENTS.md
Host template: docs/templates/AGENTS.host.md

Notes

This is not a standalone application. Use a starter or product app that composer requires the kernel and this pack.

bitshost / upmvc-saas-pack

Package info

Security

Statistics