nngo/JQC_multi_tenant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Jun 28 Optimize code

Browse Source
This commit is contained in:
nngo
2026-06-28 10:16:20 -04:00
parent ee7b0286b2
commit 45ae2b9c64
13 changed files with 536 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
MULTI_TENANT_PLAN.md
+158 -49
View File
@@ -2,7 +2,7 @@
> **Audience:** AI assistants and developers extending JQC into a multi-tenant SaaS.
> **Companion to:** `CLAUDE.md` (single-tenant architecture reference).
> **Status:** Planning. No code written yet. Existing single-tenant deploy stays live and untouched until cutover.
> **Status:** MT-0 through MT-7 complete and deployed. MT-8 flag-gated (future). MT-9 (iOS) pending.
---
@@ -74,7 +74,7 @@ tenant_audit -- superadmin actions (separate from per-ten
id, superadmin_id, action, tenant_id, details, ip_address, created_at
```
Submission quotas (inspections/issues per month) are enforced by **live-counting current-period rows in the tenant DB** at submit time (cheap with an index on the date column). No separate counter table required; always accurate. A cached `usage_counters` table is an optional later optimization if submit-path counts ever show up in profiling.
Submission quotas (inspections/issues per month) are enforced by **live-counting current-period rows in the tenant DB** at submit time (cheap with an index on the date column). No separate counter table required; always accurate.
---
@@ -82,7 +82,7 @@ Submission quotas (inspections/issues per month) are enforced by **live-counting
**Resolution** (`before_request`): `host = request.host.split(':')[0]` → look up `tenant_domains.domain == host` where `verified AND tenant.status='active'` → load `tenant` + `plan` into `g`. Unknown/unverified/suspended host → branded error/landing page (no tenant DB touched).
**Routing without rewriting every `db.session` call** — use a routing Session so the entire existing codebase keeps using `db.session` unchanged (preserves Change-Philosophy Rules 5/7):
**Routing without rewriting every `db.session` call** — use a routing Session so the entire existing codebase keeps using `db.session` unchanged:
```python
# app/tenancy/routing.py
@@ -91,31 +91,22 @@ from flask import g
class RoutingSession(Session):
def get_bind(self, mapper=None, clause=None, **kw):
# Tenant models (app.db.Model) bind to the per-request tenant engine.
# The control plane is a SEPARATE Base/engine/session (control/base.py),
# so it never passes through this session — no special-casing needed here.
return getattr(g, 'tenant_engine', None) or _default_engine
```
> **MT-0 refinement (implemented):** the control plane uses its own
> `ControlBase` + engine + session (`control/base.py`), **not** `db.Model` with
> a `__control_plane__` flag. Stronger isolation, zero metadata mixing with the
> tenant schema, and the control package imports nothing from `app/`. The
> `RoutingSession` (MT-1) therefore only handles tenant models.
> a `__control_plane__` flag. The `RoutingSession` (MT-1) therefore only handles tenant models.
```python
# app/__init__.py (one-line change to the existing db init)
db = SQLAlchemy(session_options={'class_': RoutingSession})
```
```python
# before_request
g.tenant_engine = _engine_cache.get_or_create(tenant) # create_engine(tenant.db_uri)
```
- `_engine_cache`: `dict[tenant_id -> Engine]`, lazily built, small pools + `pool_recycle`.
- **Net code change to existing models/routes: zero.**
- `_engine_cache`: `dict[tenant_id -> Engine]`, lazily built. Use small pools + `pool_recycle`; switch to `NullPool` if tenant count grows large (connection-count = Σ tenant pools). Documented scaling lever.
- The **control plane is a separate Base/engine/session** (`control/base.py`); it never routes through `RoutingSession`. See §3 MT-0 refinement.
- **Net code change to existing models/routes: zero.** They keep importing `from app import db` and calling `db.session`.
**MT-5 addition:** Plan limits and feature flags are loaded into `TenantContext` by the resolver in the same control-DB session — zero extra queries per request. `g.tenant.allow_mobile_api`, `g.tenant.max_users`, etc. are available everywhere.
---
@@ -123,16 +114,20 @@ g.tenant_engine = _engine_cache.get_or_create(tenant) # create_engine(tenant.d
Two independent Alembic chains:
1. **Tenant schema** — the existing chain (current HEAD on disk: **`phase27_score_alerts`**; note `CLAUDE.md` text says phase23 — stale). Runs per-tenant DB. New tenant features continue this chain as `phase28_…`, `phase29_…` per existing naming + `down_revision` → current HEAD rule.
2. **Control schema** — new env, chain `control{N}_…`, runs once against `jqc_control`.
1. **Tenant schema** — existing chain (HEAD: **`phase33_tenant_settings`**). Runs per-tenant DB. New tenant features continue as `phase34_…` per existing naming.
2. **Control schema** — chain `control{N}_…`, runs once against `jqc_control`. HEAD: `control0001_init`.
CLI added: `flask tenant db upgrade --tenant <id|all>` loops tenants, sets `sqlalchemy.url` to each tenant URI, runs `command.upgrade(cfg, 'head')`, writes resulting head back to `tenants.alembic_head`. All existing migrations are re-run-safe (Rule 14), so this is idempotent across the fleet.
**CLI (always source env first):**
```bash
set -a; . /etc/jqc/control.env; set +a
python -m control.tenant_migrate upgrade --tenant all
```
Deploy ordering rule carries over (CLAUDE.md Rule 23): run tenant migrations **before** shipping app code that references new columns.
Deploy ordering rule: run tenant migrations **before** shipping app code that references new columns.
---
## 6. Plan-tier matrix (starting point — tune in §9)
## 6. Plan-tier matrix
| Axis | Free | Starter | Pro | Enterprise |
|---|---|---|---|---|
@@ -146,37 +141,88 @@ Deploy ordering rule carries over (CLAUDE.md Rule 23): run tenant migrations **b
| Custom domain | ✗ | ✗ | ✓ | ✓ |
| Subdomain (`*.jqc.app`) | ✓ | ✓ | ✓ | ✓ |
Enforcement: `@feature_required('mobile_api')` reads `g.tenant.plan` and **blocks** disabled features. Quota checks (`@quota_check('inspections')`) are **soft** — over-limit submits still succeed but the response/UI flags an upgrade prompt and the event is recorded; submits are never rejected. **Feature + quota checks must live in BOTH web routes and `/api/v1` endpoints** — the iPad submits via API, so a web-only check is bypassable (mirrors existing dual-enforcement Rules 39/56/57).
Enforcement: `@feature_required('mobile_api')` hard-blocks (403) disabled features. `@quota_soft_check('inspections')` sets `g.quota_warning` but **never rejects** — over-limit submits succeed, UI shows upgrade prompt. Both decorators are **inert** when `MULTI_TENANT_ENABLED=false`.
Feature + quota checks live in **both** web routes and `/api/v1` endpoints (iPad submits via API — web-only check is bypassable).
---
## 7. Phased roadmap
Each phase additive; existing tenant-zero traffic keeps working throughout.
**MT-0 — Control-plane scaffold. ✅ DONE.**
Self-contained `control/` package: own `ControlBase` + engine + session, own Alembic chain (`control0001_init`), 7 models, Fernet-encrypted tenant creds, idempotent plan seeder, operator CLI. Zero imports into `app/`.
**MT-0 — Control-plane scaffold. ✅ DONE.** Self-contained `control/` package at repo root: own `ControlBase` + engine + session, own Alembic chain (`control0001_init`), 7 models, Fernet-encrypted tenant creds, idempotent plan seeder, operator CLI. Zero imports into `app/` — existing app untouched.
**MT-1 — Tenant resolution + routing. ✅ DONE.**
`app/tenancy/` package: `RoutingSession`, `resolve_tenant()`, `engine_cache`, `TenantContext`, `init_tenancy()` before_request hook + branded 404. Gated behind `MULTI_TENANT_ENABLED=false` — fully inert until flipped.
**MT-1 — Tenant resolution + routing. ✅ DONE.** `app/tenancy/` package: `routing.py` (`RoutingSession` subclassing the Flask-SQLAlchemy session), `resolver.py` (Host→tenant via control plane, lazy import), `engine_cache.py` (per-tenant engines), `context.py` (`TenantContext`), `middleware.py` (`init_tenancy` before_request hook + branded unknown-host 404). Edits: `db` init in `app/__init__.py` (+`init_tenancy(app)` call) and `MULTI_TENANT_ENABLED` + pool flags in `config.py`. Gated behind `MULTI_TENANT_ENABLED` (default False) — fully inert until flipped.
**MT-2 — Per-tenant migration runner. ✅ DONE.**
`migrations_tenant/env.py` + `control/tenant_migrate.py` (`upgrade_tenant`, `bootstrap_tenant`, `chain_head`, CLI). Guarded squashed baseline `0003_add_user_active` restores chain root. Fresh DBs use `bootstrap_tenant` (baseline → stamp head, skips unguarded phase migrations). Incremental upgrades use `upgrade_tenant` (phase33+).
**MT-2 — Per-tenant migration runner. ✅ DONE (with blocker found).** Standalone `migrations_tenant/env.py` (reads URL from config, reuses `migrations/versions` via `version_locations`, no Flask) + `control/tenant_migrate.py` (`upgrade_tenant()`, `current_revision()`, `chain_head()`, CLI: `python -m control.tenant_migrate upgrade|current|heads --tenant <id|slug|all>`). Records `tenants.alembic_head` + a `ProvisioningJob('migrate')` per run. Existing `migrations/env.py` untouched (normal `flask db` still works).
> **⚠ Blocker found by MT-2 — RESOLVED.** Chain had no base; 14/30 phase migrations unguarded. Fixed by guarded squashed baseline. Fresh DB provisioning must use `bootstrap_tenant`, never raw `flask db upgrade`.
> **⚠ Blocker found by MT-2 — RESOLVED.** The live `migrations/versions` chain had **no base**: `phase1_projects_roles.down_revision = '0003_add_user_active'` pointed at a missing revision, and 14/30 phase migrations are not idempotent. **Fix:** a guarded squashed baseline `migrations/versions/0003_add_user_active.py` (`down_revision = None`) that recreates the full current schema (generated from the models, 25 tables, INFORMATION_SCHEMA-guarded) — restoring the chain root. Fresh tenants are built via `bootstrap_tenant()` = upgrade to the baseline **then `stamp head`**, so the non-idempotent phase migrations are never replayed. Existing DBs (LT) are at a later head, so the baseline is treated as applied ancestry and never runs. Ongoing migrations (phase33+, which MUST be guarded) apply incrementally to all tenants via `upgrade_tenant()`.
>
> **Operational note:** any *fresh* database (including a new dev DB) must use the bootstrap flow, not a naive `flask db upgrade` from empty, because the historical phase replay still hits the unguarded migrations. Cross-check the baseline against `mysqldump --no-data` of LT and test `bootstrap` on a scratch MySQL before going live.
**MT-3 — Provisioning service. ✅ DONE.**
`control/provision.py`: `create_tenant()` (DB + user + schema + admin seed + domain), `register_tenant_zero()` (adopt LT DB in place), `delete_tenant()`. Fernet-encrypted creds, `provisioning_jobs` logged. CLI: `python -m control.provision`.
**MT-3 — Provisioning service. ✅ DONE.** `control/provision.py`: `create_tenant()` (admin account from `PROVISION_DB_URL` creates per-tenant DB + least-privilege user + grant → `bootstrap_tenant` builds schema + stamps head → `seed_admin` inserts the first admin with a set-password token → registers subdomain + optional custom domain → status active; best-effort rollback drops the DB/user + tenant row on failure). `register_tenant_zero()` adopts an existing DB in place (no DB/user creation, no bootstrap; reads its current head, maps `lts.<base>` + LT's live domain as a verified custom domain — zero data movement). `delete_tenant()` removes control records, optional guarded DB drop (refuses non-provisioner-named DBs, protecting tenant-zero). CLI: `python -m control.provision create-tenant|register-tenant-zero|delete-tenant`. Admin setup link uses `/customers/set-password/<token>` (the route that sets `password_set=True`). Creds Fernet-encrypted; `provisioning_jobs`-logged.
**MT-4 — Superadmin control panel. ✅ DONE.**
Standalone Flask app at `admin.jqc.app` (`control/panel/`). WSGI entry: `control/panel/wsgi_panel.py` → Gunicorn on port 8001 (`jqc-panel.service`). Separate Nginx server block — **must appear before the `*.jqc.app` wildcard block** or Nginx routes `admin.jqc.app` to port 8000 (main app).
**MT-4 — Superadmin control panel.** Tenant CRUD, plan assign, suspend/resume, domain mgmt, migration status, impersonation (scoped login into a tenant for support). At `admin.jqc.app`, separate blueprint, superadmin-gated.
Routes: tenant list/detail, plan change, suspend/resume, domain CRUD (add/verify/delete), migration status + upgrade trigger, provision new tenant, impersonation.
**MT-5 — Plans + quota/feature gating.** `@feature_required`, `@quota_check`; new cross-tenant `superadmin` (control plane). Existing tenant `admin` = top role within a tenant (unchanged ENUM).
**Impersonation flow:**
1. Panel generates HMAC-SHA256 signed token (`PANEL_IMPERSONATE_KEY`, TTL 60 s).
2. Redirects to `https://<tenant-primary-domain>/auth/impersonate?token=<t>`.
3. Main app validates token, sets `session['impersonating_tenant_id']`.
4. Tenancy middleware reads this key and short-circuits Host resolution.
5. "End impersonation" banner clears key, redirects back to `admin.jqc.app`.
**MT-6 — Custom domain + TLS.** Wildcard cert for `*.jqc.app`; Caddy on-demand TLS in front for arbitrary custom domains. Domain-verification flow (TXT/CNAME) before activation.
Required env vars (add to `/etc/jqc/control.env`):
```
PANEL_SECRET_KEY=<hex32>
PANEL_IMPERSONATE_KEY=<hex32>
```
**MT-7 — Tenant self-service.** Tenant-admin: branding (logo/name/colors), domain request, plan view, in-plan feature toggles. User mgmt auto tenant-scoped by routing.
**MT-5 — Plans + quota/feature gating. ✅ DONE.**
`app/tenancy/quota.py` — live counters (inspections/issues this month, total users/facilities) against tenant DB.
`app/tenancy/gates.py` — `@feature_required(key)` (hard 403) and `@quota_soft_check(axis)` (sets `g.quota_warning`, never rejects).
`app/tenancy/context.py` — `TenantContext` extended with 9 plan fields (all default to unlimited/True → single-tenant unchanged).
`app/tenancy/resolver.py` — loads `plan` in the same control session, populates `TenantContext` plan fields.
`app/templates/_quota_warning.html` — reusable upgrade-prompt banner partial.
**MT-8 — Billing (future).** Stripe per-plan; lifecycle (trial/suspend/dunning). Flag-gated.
Gated routes:
**MT-9 — iOS multi-tenant.** Replace hardcoded `ServerOption` enum (`Utils/Constants.swift`) with onboarding: enter subdomain or work-email → discovery endpoint resolves base URL → store per-tenant in Keychain. All `/api/v1` calls unchanged (server resolves tenant by Host). Tenant-zero keeps `jqc.ltservicesinc.com` as a custom domain so existing builds keep working through rollout.
| Route | Gate |
|---|---|
| `inspections.start()` | `@quota_soft_check('inspections')` |
| `issues.create()` | `@quota_soft_check('issues')` |
| `auth.create_user()` | `@quota_soft_check('users')` |
| `facilities.create_facility()` | `@quota_soft_check('facilities')` |
| `scheduled_reports.index()` + `create()` | `@feature_required('scheduled_reports')` |
| `api.create_inspection()` | `@feature_required('mobile_api')` + `@quota_soft_check('inspections')` |
| `api.create_issue()` | `@feature_required('mobile_api')` + `@quota_soft_check('issues')` |
Decorator stack order: `@login_required` → `@role_required` → `@feature_required` → `@quota_soft_check`.
**MT-6 — Custom domain + TLS. ⚙ INFRASTRUCTURE ONLY — no Python deliverables.**
Wildcard cert `*.jqc.app` via DNS-01 challenge (certbot + DNS plugin). Custom-domain TLS via Caddy on-demand TLS. Domain-verification flow (TXT/CNAME) already in MT-7 self-service UI; superadmin marks `verified=True` in the control panel after DNS check. When Caddy is deployed, update Nginx to pass custom domains to Caddy rather than directly to port 8000.
**MT-7 — Tenant self-service. ✅ DONE.**
`app/models/tenant_settings.py` — `TenantSettings` model, one row per tenant DB, `get_or_default()` returns transient defaults when no row exists (zero migration burden for existing tenants).
`app/routes/tenant_settings.py` — blueprint at `/settings/`, `@admin_required`.
`app/templates/tenant_settings/` — `branding.html`, `plan.html`, `domains.html`.
Migration: `phase33_tenant_settings` (INFORMATION_SCHEMA guarded, safe to re-run).
Branding injection: `inject_tenant_branding()` context processor in `app/__init__.py` pushes `tenant_branding` into every template. `base.html` patches: navbar brand reads logo/name from `tenant_branding`; CSS vars `--bs-primary`, `--jqc-accent` injected via inline `<style>` from `tenant_branding.primary_color` / `accent_color`. Jinja2 filter `hex_to_rgb` registered for Bootstrap RGB var.
Self-service features:
- **Branding**: company name, logo upload (magic-byte validated), primary/accent colours, support email. Gated by `allow_branding` — shows warning but doesn't block form (soft, consistent with quota philosophy).
- **Plan & Usage**: read-only plan info + live quota progress bars (reads from control DB + tenant DB live counts). "Request upgrade" mailto link.
- **Domains**: lists all `TenantDomain` rows. Admin can request a custom domain (creates unverified row, shows TXT/CNAME DNS instructions). Delete unverified custom domains. Superadmin does final verification via control panel.
**MT-8 — Billing. 🔲 FUTURE — flag-gated.**
Stripe per-plan subscription. Lifecycle: trial → active → past_due → suspended → cancelled. Dunning emails. All behind a `BILLING_ENABLED` feature flag. No code written.
**MT-9 — iOS multi-tenant. 🔲 PENDING.**
Server side: `GET /api/v1/discover?subdomain=acme` and `GET /api/v1/tenant` public endpoints — exempt from tenant middleware via `MULTI_TENANT_EXEMPT_PATHS`. iOS side: pending (web-first priority).
---
@@ -185,23 +231,86 @@ Each phase additive; existing tenant-zero traffic keeps working throughout.
Register the **existing live LT database in place** — no dump/reload:
1. Insert `tenants` row (id 1), `db_*` pointing at the current LT DB + creds. Record its current alembic head.
2. Insert `tenant_domains`: primary subdomain `lts.jqc.app`; plus `jqc.ltservicesinc.com` (kind=custom, verified) so existing web users **and** existing iPad builds keep working with zero disruption.
3. Point wildcard DNS / Caddy at the (now tenant-aware) app. Resolver returns tenant 1 for both hosts.
2. Insert `tenant_domains`: primary subdomain `lts.jqc.app`; plus `jqc.ltservicesinc.com` (kind=custom, verified) so existing web users keep working.
3. Point wildcard DNS / Nginx at the (now tenant-aware) app. Resolver returns tenant 1 for both hosts.
Result: existing users notice nothing; LT is now just "tenant 1" inside the new model.
Result: existing users notice nothing; LT is now "tenant 1".
---
## 9. Decisions resolved — MT-0 unblocked
## 9. Decisions resolved
1. **Quota-exceed** → soft warn (allow + flag upgrade). Never reject. §6.
2. **Tenant DB credentials** → per-tenant MySQL user + password; provisioning creates user/grants scoped to the single tenant DB; creds encrypted at rest. §3, MT-3.
3. **Tenant-zero** → register existing live LT DB in place, no data move. §8.
1. **Quota-exceed** → soft warn (allow + flag upgrade). Never reject.
2. **Tenant DB credentials** → per-tenant MySQL user + password; creds encrypted at rest.
3. **Tenant-zero** → register existing live LT DB in place, no data move.
4. **Impersonation** → HMAC-signed token (60 s TTL), panel→tenant redirect, session key short-circuits Host resolution.
5. **Branding gate** → soft (shows warning, form still usable) — consistent with quota philosophy.
All planning decisions locked. Ready to begin **MT-0** (control-plane scaffold) on request.
---
### MT-0 first deliverables (preview)
- `jqc_control` database + control Alembic env (`control0001_init`).
- Control models on a dedicated `ControlBase`: `Plan`, `PlanFeature`, `Tenant`, `TenantDomain`, `Superadmin`, `ProvisioningJob`, `TenantAudit`.
- Plan seeder (Free / Starter / Pro / Enterprise per §6 matrix).
- No data-plane change in MT-0 — existing app keeps running against the LT DB exactly as today.
## 10. Nginx — block ordering (critical)
```nginx
# /etc/nginx/sites-available/jqc
# 1. PANEL — exact match, must be FIRST
server {
listen 80;
server_name admin.jqc.app;
location / { proxy_pass http://127.0.0.1:8001; ... }
}
# 2. APEX redirect — jqc.app has no registered tenant
server {
listen 80;
server_name jqc.app;
return 301 http://lts.jqc.app$request_uri;
}
# 3. WILDCARD — all tenant subdomains
server {
listen 80;
server_name *.jqc.app;
location / { proxy_pass http://127.0.0.1:8000; ... }
}
```
If `admin.jqc.app` is in the same block as `*.jqc.app`, Nginx routes it to port 8000 (main app), which returns "Workspace not found" because `admin.jqc.app` is not a registered tenant domain.
---
## 11. CLI quick-reference
```bash
# Source env first — CONTROL_DATABASE_URL not in interactive shell by default
set -a; . /etc/jqc/control.env; set +a
# Control schema + plans + first superadmin (run once)
alembic -c control/migrations/alembic.ini upgrade head
python -m control.cli seed
python -m control.cli create-superadmin --username admin --email you@example.com
# Adopt existing LT database as tenant-zero (run once, no data move)
python -m control.provision register-tenant-zero \
--slug lts --name "LT Services" --plan enterprise \
--db-host 127.0.0.1 --db-name <LT_DB> --db-user <LT_USER> --db-password '<pw>' \
--custom-domain jqc.ltservicesinc.com --base-domain jqc.app
# Provision a new tenant
python -m control.provision create-tenant \
--slug acme --name "Acme Corp" --plan pro --admin-email ops@acme.com
# Delete / deregister a tenant
python -m control.provision delete-tenant --slug ztest --drop-db --yes
python -m control.provision delete-tenant --slug lts --yes # no --drop-db for adopted DB
# Migration status + upgrades
python -m control.tenant_migrate heads
python -m control.tenant_migrate current --tenant all
python -m control.tenant_migrate upgrade --tenant all # incremental (phase33+)
python -m control.tenant_migrate bootstrap --tenant acme # fresh DB only
# Superadmin panel
sudo systemctl status jqc-panel
sudo systemctl restart jqc-panel
```