SaaS Operating
System

Copy-paste into Claude. Replace all tokens before pasting. The prompt enforces plan-first execution — Claude outputs a numbered plan and waits for "proceed" before writing any file. Clicking Mark as Used sets Environment Setup Guide and Runbook to Draft in the tracker and moves Pillar 2 to In Progress.

You are a senior backend engineer scaffolding a new multi-tenant SaaS product.
Prompt version: v0.3

── TOKENS (replace all before pasting) ──────────────────────────────
PRODUCT_NAME:      {{PRODUCT_NAME}}
AUTH_PROVIDER:     {{AUTH_PROVIDER}}       # Auth0 | Clerk | Supabase
DB_NAME:           {{DB_NAME}}
PORT:              {{PORT}}
FRAMEWORK:         {{FRAMEWORK}}           # flask | fastapi
TENANT_ISOLATION:  {{TENANT_ISOLATION}}    # rls | app-layer
─────────────────────────────────────────────────────────────────────

─── PLAN FIRST ───────────────────────────────────────────────────────
Before writing any files, output a numbered list of every file
you will create and its purpose. Wait for the user to reply
"proceed" before generating any code.
─────────────────────────────────────────────────────────────────────

Scaffold the following when proceeding:

1. Project structure
   {{PRODUCT_NAME}}/
   ├── app/
   │   ├── __init__.py
   │   ├── config.py              # 12-Factor: all config from env vars; no hardcoded values
   │   ├── auth.py                # {{AUTH_PROVIDER}} middleware — verify token, attach user to request
   │   ├── context.py             # resolve_org_context() → {user_id, org_id, role} from token + DB
   │   ├── routes/
   │   │   ├── health.py          # GET /api/health → {"status":"ok","env":"...","ts":"..."}
   │   │   ├── me.py              # GET /api/me → {user_id, org_id, role, org_name}
   │   │   ├── billing.py         # POST /api/webhooks/zoho — HMAC verify, dispatch to stubs
   │   │   └── __init__.py
   │   ├── models/
   │   │   ├── base.py            # SQLAlchemy base; id (UUID PK) + org_id (UUID NOT NULL) + timestamps
   │   │   ├── org.py             # Org(id, name, slug, plan, created_at)
   │   │   ├── user.py            # User(id, email, auth_provider_id, created_at)
   │   │   └── membership.py      # Membership(id, org_id FK, user_id FK, role)
   │   └── middleware/
   │       └── rbac.py            # @require_role('admin'|'member') — API layer only, not UI
   ├── migrations/
   │   ├── env.py                 # Alembic: include_schemas=True; target_metadata from Base
   │   └── versions/              # empty — ready for first migration
   ├── scripts/
   │   ├── backup.sh              # pg_dump -Fc + timestamp; exit non-zero on failure; 30-day retention
   │   ├── restore.sh             # "type YES" confirmation gate; pg_restore --clean --if-exists
   │   └── workdrive_upload.sh    # stub: upload latest dump to Zoho WorkDrive (wire MCP when ready)
   ├── docker-compose.yml         # dev: ${BIND_HOST:-127.0.0.1}:${PORT}:${PORT}; dev volumes mounted
   ├── docker-compose.staging.yml # staging overlay: same image tag; no dev volumes; .env.staging
   ├── .env.example               # all required vars with placeholder values — no real secrets
   ├── .env.staging.example       # staging-specific vars, all placeholders
   ├── .gitignore                 # blocks .env*, backups/, *.pgdump, __pycache__
   ├── README.md                  # project name, token list, quickstart, link to RUNBOOK.md
   ├── RUNBOOK.md                 # start/stop, migrations, backup/restore, deploy, rollback
   ├── requirements.txt
   └── alembic.ini

2. Config (config.py) — required env vars
   DATABASE_URL              # postgresql+psycopg2://user:pass@host/db
   SECRET_KEY                # no default — must be set explicitly
   {{AUTH_PROVIDER}}_DOMAIN
   {{AUTH_PROVIDER}}_CLIENT_ID
   {{AUTH_PROVIDER}}_CLIENT_SECRET
   ZOHO_WEBHOOK_SECRET       # HMAC verification key
   BIND_HOST                 # default 127.0.0.1; set 0.0.0.0 for LAN/Tailscale exposure
   CORS_ALLOWED_ORIGINS      # comma-separated list of allowed origins
   CORS_ALLOW_CREDENTIALS    # true | false
   FRONTEND_ORIGIN           # convenience alias; auto-added to CORS_ALLOWED_ORIGINS
   ENV                       # dev | staging | production
   WORKDRIVE_FOLDER_ID       # Zoho WorkDrive folder for backup uploads (optional)

3. Multi-tenant primitives
   · Org, User, Membership models as defined above
   · org_id UUID NOT NULL + index on every application table
   · resolve_org_context(request): token subject → User → Membership → {user_id, org_id, role}
     Raise 403 if no active membership found
   · GET /api/me: call resolve_org_context(); return context + org_name; require auth
   · Tenant isolation — controlled by TENANT_ISOLATION env var:
     "rls"        → ALTER TABLE ... ENABLE ROW LEVEL SECURITY; CREATE POLICY using
                    current_setting('app.current_org')::UUID; set via DB session var
     "app-layer"  → no RLS; every query filters by org_id explicitly; include test stubs
                    asserting cross-tenant queries return zero rows

4. Zoho billing seam (billing.py)
   · POST /api/webhooks/zoho
   · Step 1: verify HMAC-SHA256(payload, ZOHO_WEBHOOK_SECRET) — return 401 on mismatch
   · Step 2: parse event_type from payload body
   · Step 3: dispatch to stub handlers:
       subscription_activated(payload)
       subscription_cancelled(payload)
       subscription_renewed(payload)
       payment_failed(payload)
   · Principle: Zoho is source of truth — DB reflects what Zoho sends, not the reverse
   · Each stub must log event_type and payload keys before returning 200

5. Backup, restore, and offsite upload
   backup.sh:
     · set -euo pipefail; pg_dump -Fc; timestamped filename; exit non-zero on failure
     · 30-day local retention (find ... -mtime +30 -delete)
     · On success, exec scripts/workdrive_upload.sh "$FILE"
   restore.sh:
     · Takes backup file path as $1; abort with usage if missing
     · Print target DB + file; prompt "Type YES to continue"
     · pg_restore -U $DB_USER -d $DB_NAME --clean --if-exists
   workdrive_upload.sh:
     · Reads WORKDRIVE_FOLDER_ID from env
     · Stub: echo upload intent + curl skeleton to Zoho WorkDrive Files API
     · Comment: # TODO: wire Zoho MCP tool here when available

6. Environment separation
   docker-compose.yml         dev; ${BIND_HOST:-127.0.0.1} binds; source-mounted app volume
   docker-compose.staging.yml staging overlay; no app volume mount; uses .env.staging;
                               same pinned image tag; add healthcheck config
   .env.example               dev vars only; all placeholders
   .env.staging.example       staging vars; ENV=staging; separate DB_NAME and SECRET_KEY slots
   Rule: staging and production env files must never be used locally without explicit intent

7. Network and CORS
   · CORS middleware reads CORS_ALLOWED_ORIGINS (split on comma) + FRONTEND_ORIGIN
   · CORS_ALLOW_CREDENTIALS controls credentials header
   · docker-compose port binding: "${BIND_HOST:-127.0.0.1}:${PORT}:${PORT}"
   · No hardcoded bind addresses anywhere in compose files

   Document these reachability modes in README.md:
   Mode 1 — Local only (default, safe):
     BIND_HOST=127.0.0.1 — reachable only from localhost
   Mode 2 — LAN / Tailscale:
     BIND_HOST=0.0.0.0 — reachable on LAN or Tailscale network
     Set CORS_ALLOWED_ORIGINS to include Tailscale hostname
     Note: confirm firewall rules before enabling
   Mode 3 — Reverse proxy / tunnel:
     Keep BIND_HOST=127.0.0.1; expose via Tailscale Funnel or Cloudflare Tunnel
     CORS_ALLOWED_ORIGINS = public domain only

8. Git hygiene
   .gitignore must cover:
     .env, .env.*, !.env.example, !.env.staging.example
     __pycache__/, *.pyc, *.egg-info/, .venv/
     /backups/, /data/, /uploads/, *.pgdump, *.sql
   README.md must include:
     · One-line product description
     · Full token list (all {{TOKENS}} used in this prompt)
     · Quickstart: clone → copy .env.example → fill secrets → docker-compose up
     · Link to RUNBOOK.md
   RUNBOOK.md must include:
     · Start / stop service
     · Run / rollback migrations (alembic upgrade head / downgrade -1)
     · Create backup and test restore (scripts/backup.sh / scripts/restore.sh)
     · Deploy to staging (docker-compose -f docker-compose.staging.yml up -d)
     · Rollback procedure

9. Constraints (enforced across all generated files)
   · No secrets in any tracked file — .env.example and .env.staging.example only
   · Auth via middleware only — no per-route token parsing
   · org_id filter applied at the repository/service layer in every query
   · Zoho HMAC verified before any webhook payload is processed
   · backup.sh exits non-zero on pg_dump failure
   · All compose port bindings use ${BIND_HOST} — no hardcoded addresses

10. After scaffolding, print this verification checklist:

    ── Environment ──────────────────────────────────────────────────
    [ ] cp .env.example .env && fill in all required values
    [ ] docker-compose up -d && docker-compose ps  → all containers Up
    [ ] docker exec backend alembic upgrade head   → no errors
    [ ] curl http://${BIND_HOST}:${PORT}/api/health → {"status":"ok"}

    ── Multi-tenant ─────────────────────────────────────────────────
    [ ] Seed: create test Org + User + Membership via psql or seed script
    [ ] GET /api/me with valid token → {user_id, org_id, role, org_name}
    [ ] Cross-tenant isolation:
        SET app.current_org = '<org-a-id>';
        SELECT COUNT(*) FROM <table> WHERE org_id != '<org-a-id>';
        # Expected: 0

    ── Billing seam ─────────────────────────────────────────────────
    [ ] POST /api/webhooks/zoho with bad signature  → 401
    [ ] POST /api/webhooks/zoho with valid signature → 200, event logged

    ── Reachability ─────────────────────────────────────────────────
    [ ] Mode 1: BIND_HOST=127.0.0.1 — curl from localhost succeeds
    [ ] Mode 2: BIND_HOST=0.0.0.0  — curl from LAN device succeeds
    [ ] Mode 3: tunnel configured  — curl via Tailscale/Cloudflare hostname succeeds

    ── Git hygiene ──────────────────────────────────────────────────
    [ ] git grep -rn "password\|secret\|api_key" -- "*.py" "*.yml" | grep -v ".env.example"
        # Expected: no output
    [ ] git status does not show .env (gitignore working)
    [ ] README.md and RUNBOOK.md present and non-empty

Generated from system audit — not hand-authored. Regenerate after any service change. All AI agents must read this before any infrastructure action.

# STACK_CONTEXT.md
# Generated: {{DATE}} — system audit, not hand-authored.
# Regenerate after any service is added, removed, or reconfigured.
# Required reading for all AI agents before infrastructure actions.

## Host
Host:       {{HOSTNAME}}
LAN IP:     {{LAN_IP}}
Tailscale:  {{TAILSCALE_IP}} / {{TAILSCALE_HOSTNAME}}

## Running Services
| Container | Image | Port Binding | Status |
|-----------|-------|-------------|--------|
| {{name}}  | {{image}} | 0.0.0.0:{{port}} | Up Nh |

## Port Map
| Port | Service | Runtime | Bound To | Compose File |
|------|---------|---------|----------|-------------|
| {{port}} | {{service}} | Docker / native | 0.0.0.0 / 127.0.0.1 | {{file}} |

## Not Yet Deployed
| Service | Planned Port | Status |
|---------|-------------|--------|
| {{service}} | {{port}} | Not deployed |

## Connectivity
Tailscale:          active / inactive
Cloudflare Tunnel:  active / inactive

## Assumptions
- ASSUMPTION: ...

Update before deploying any new service. Resolve conflicts here — before they reach production.

# PORT_REGISTRY.md
# RULE: Update this file before deploying any new service.
# RULE: Resolve port conflicts here — before they reach production.
# Last updated: {{DATE}}

| Port | Service | Runtime | Bound To | Compose File | Status |
|------|---------|---------|----------|-------------|--------|
| 5000 | backend  | Docker | 0.0.0.0 | docker-compose.yml | active  |
| 5432 | postgres | Docker | 0.0.0.0 | docker-compose.yml | active  |
| 8080 | frontend | Docker | 0.0.0.0 | docker-compose.yml | active  |
| {{port}} | {{service}} | — | — | — | planned |

## Conflict Log
| Date | Port | Conflict | Resolution |
|------|------|----------|-----------|
| {{date}} | {{port}} | {{description}} | {{resolution}} |

Git-tracked under scripts/. All use set -euo pipefail. Configured via env vars — no hardcoded values.

── backup.sh ──────────────────────────────────────────────────────
#!/usr/bin/env bash
set -euo pipefail
DB_CONTAINER="${DB_CONTAINER:-db}"
DB_NAME="${DB_NAME:-app}"
DB_USER="${DB_USER:-app}"
BACKUP_DIR="${BACKUP_DIR:-./backups}"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
FILE="${BACKUP_DIR}/${DB_NAME}_${TIMESTAMP}.pgdump"
mkdir -p "$BACKUP_DIR"
echo "→ Dumping ${DB_NAME}…"
docker exec "$DB_CONTAINER" pg_dump -U "$DB_USER" -Fc "$DB_NAME" > "$FILE"
echo "✓ Backup: $(du -sh "$FILE" | cut -f1)"
find "$BACKUP_DIR" -name "*.pgdump" -mtime +30 -delete   # 30-day retention

── restore.sh ─────────────────────────────────────────────────────
#!/usr/bin/env bash
set -euo pipefail
BACKUP_FILE="${1:?Usage: restore.sh <backup.pgdump>}"
DB_CONTAINER="${DB_CONTAINER:-db}"
DB_NAME="${DB_NAME:-app}"
DB_USER="${DB_USER:-app}"
echo "⚠  This will OVERWRITE ${DB_NAME}. File: ${BACKUP_FILE}"
printf "   Type YES to continue: "; read -r CONFIRM
[[ "$CONFIRM" == "YES" ]] || { echo "Aborted."; exit 1; }
docker exec -i "$DB_CONTAINER" pg_restore \
  -U "$DB_USER" -d "$DB_NAME" --clean --if-exists < "$BACKUP_FILE"
echo "✓ Restore complete."

── health-check.sh ────────────────────────────────────────────────
#!/usr/bin/env bash
set -euo pipefail
PORT="${PORT:-5000}"
echo "── Containers ──────────────────────────────────────────"
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
echo "── Migration state ─────────────────────────────────────"
docker exec backend alembic current 2>/dev/null || echo "  (unreachable)"
echo "── Health endpoint ─────────────────────────────────────"
curl -sf "http://127.0.0.1:${PORT}/api/health" | python3 -m json.tool \
  || echo "  ✗ Health check failed"

org_id on every application table — indexed, NOT NULL. RLS enabled before any customer data enters production. Run the validation query as the app DB user, not the postgres superuser.

-- Every application table follows this baseline.
-- Replace 'resources' with your entity name.

CREATE TABLE resources (
    id          UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
    org_id      UUID        NOT NULL,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
    -- add domain columns here
);

CREATE INDEX idx_resources_org_id ON resources (org_id);

-- Row-Level Security — enable before any customer data enters
ALTER TABLE resources ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON resources
    USING (org_id = current_setting('app.current_org')::UUID);

-- alembic/env.py — required additions
-- from app.models.base import Base
-- target_metadata = Base.metadata
-- include_schemas = True

-- Validation (run as app DB user — not postgres superuser)
SET app.current_org = 'aaaaaaaa-0000-0000-0000-000000000000';
SELECT COUNT(*) FROM resources;
-- Expected: 0  (org has no data — confirms RLS is enforced)

Run in order. All six must pass before marking Pillar 2 in progress.

# 1 — Running containers
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 2 — Migration state (must show a head revision — not "None")
docker exec backend alembic current

# 3 — Health endpoint (expect {"status": "ok"})
curl -s http://127.0.0.1:$PORT/api/health | python3 -m json.tool

# 4 — Zoho webhook reachable (expect 200 or 400 — not 404)
curl -s -o /dev/null -w "%{http_code}" \
  -X POST http://127.0.0.1:$PORT/api/webhooks/zoho

# 5 — RLS active (run as app DB user — not postgres superuser)
docker exec -it db psql -U $DB_USER -d $DB_NAME -c \
  "SET app.current_org = 'aaaaaaaa-0000-0000-0000-000000000000';
   SELECT COUNT(*) FROM resources;"
# Expected: 0 rows — confirms tenant isolation is enforced

# 6 — No secrets in tracked files
git grep -rn "password\|secret\|api_key\|token" -- "*.py" "*.yml" "*.env" \
  | grep -v ".env.example"
# Expected: no output

The Playbook enforces discipline without punishing early-stage execution. Priority tiers prevent premature overbuild — not every criterion carries the same cost of delay. Tier 1 items protect architecture: their absence forces structural teardowns at the worst possible time. Tier 2 items protect customers: they must exist before production exposure or first revenue. Tier 3 items protect scale: they are not optional, but their absence does not block safe early iteration. Completion of Tier 1 enables safe feature development.