Flow Diagrams
Three maps. The outcome map asks what success looks like. The dependency map asks what it sits on. The value stream map traces the flow from operator intent to customer access.
Outcome Map
What does a superadmin need to make happen, and how does success change?
CURRENT STATE TARGET STATE ───────────────────────────────────── ────────────────────────────────────── Superadmin needs org created Superadmin fills form at /admin/orgs/new → opens DB client → org created in < 30s → writes INSERT manually → visible in org list immediately Login goes straight to dashboard Login detects multiple orgs → single org assumed → org picker appears → no way to switch orgs → user selects org, enters dashboard Resource types only via seed function Resource types editable in /admin/reference-data → requires code change + deploy → INSERT row via UI → requires developer → active in permission matrix same day admin.dreamineering.com → 403 admin.dreamineering.com → /admin → Better Auth invalid origin → trustedOrigins updated → deployed but broken → fully operational
| Outcome | Pass | Fail |
|---|---|---|
| Org creation | New org in DB within 30s of form submit | 404 on /admin/orgs/new, or DB insert required |
| Org picker | User with 2+ orgs sees selector at login | Dashboard loads without asking which org |
| Resource type insert | New type in roles permission matrix | Still requires seed function re-run |
| Superadmin isolation | Org admin cannot reach /admin/* | Any user can browse to /admin |
| Cross-org queries | Superadmin sees all orgs; admin sees zero others | Org admin can view other org members |
The outcome map names what success looks like. The dependency map asks what it sits on. What does the admin portal sit on, and what sits on it?Dependency Map
Admin Portal
│
├── DEPENDS ON (must exist first)
│ ├── Better Auth authentication [LIVE]
│ │ └── Custom claims (role=superadmin) [GAP — claim not yet defined]
│ │ └── trustedOrigins [GAP — admin.dreamineering.com missing]
│ ├── Multi-tenancy schema [LIVE]
│ │ ├── organisations table [LIVE]
│ │ ├── organisationId FK on all tenant tables [LIVE]
│ │ └── org creation server action [GAP — does not exist]
│ ├── Next.js middleware [LIVE]
│ │ └── Superadmin bypass layer [GAP — not written]
│ └── governance_resource_types table [LIVE — seed only, no UI]
│
└── ENABLES (blocked until this exists)
├── Customer 2 onboarding [BLOCKED]
├── Multi-org login flow [BLOCKED]
├── New resource types without a developer [BLOCKED]
└── Org lifecycle management (suspend, archive) [BLOCKED]Critical Path
AUTHZ-004: Superadmin auth claim + middleware guard
↓
ORG-001: Org create + list at /admin
↓ (parallel)
ORG-002: Org picker on login REF-001: Reference data UI at /admin/reference-data
↓
ORG-003: Org suspend/archiveBlast Radius
Layer Impact Risk Middleware All routes pass through it Superadmin bypass must not weaken org-scoped protection organisations table Schema unchanged — new INSERTs only Low — additive only governance_resource_types New UI adds rows; existing rows unchanged Low — UI is additive Login flow Org picker adds conditional step Medium — must not break single-org login All server actions Still scoped by organisationId None — superadmin bypass is middleware-only
The dependency map names what must exist. The value stream traces the flow. How does value flow from operator intent to customer access? Which flow diagram in the admin portal set reveals an assumption that doesn't survive contact with a real multi-tenant database?Value Stream Map
OPERATOR INTENT SYSTEM PROCESSING CUSTOMER VALUE
────────────────── ────────────────── ──────────────
1. "Create org for Customer 2" Better Auth validates superadmin Customer 2 signs in
↓ claim in session ↓
2. Navigate to /admin/orgs/new ↓ Org picker renders
↓ Middleware allows /admin/* access ↓
3. Fill name + slug ↓ Selects their org
↓ createOrgAction() INSERTs row ↓
4. Submit ↓ Lands on dashboard
↓ Org appears in list + picker ↓
5. Invite customer admin ↓ Customer admin manages
Auth callback detects multi-org their own users
↓
Org picker rendered
↓
Customer selects org → dashboard
CYCLE TIME TARGET: < 5 minutes from operator intent to customer first login
CURRENT CYCLE TIME: ∞ (requires developer + DB access + deploy)Value Bottlenecks
Bottleneck Current Target Auth origin 403 — admin domain not trusted Config fix — minutes Org creation Requires developer + DB Form submit — 30 seconds Org switching Impossible — hardcoded to single org Org picker at login Reference data Code change + deploy Admin UI — same session Questions