Audience: Everyone
Outcomes: Shared mental model; correct isolation; least-privilege access
Glossary (core entities)
Organization (Org) — tenant boundary; owns users, settings, contracts, orders, invoices, disputes, scores.
User — belongs to exactly one org at a time; has a role and KYC status.
Partner link — approved trust relationship between two orgs; required for cross-org contracts.
Contract — structured agreement; lifecycle: draft → review → approve/reject → sign → active.
Order — execution unit under a contract; contains milestones & deliverables.
Milestone — scope + acceptance criteria + (optional) escrow release amount.
Deliverable — uploaded artifact(s) attached to an order/milestone.
Payment — card/bank/crypto transaction recorded against an order.
Escrow — custodial account or smart contract releasing funds by milestone.
Dispute — formal conflict tied to an order; resolved by admin decision.
Invoice — document of record for charges/refunds.
Reputation — per-org score derived from delivery, disputes, refunds.
Relationships (canonical diagram)
flowchart LR OrgA[Organization A] -- partner link --> OrgB[Organization B] OrgA --- UsersA[Users] OrgB --- UsersB[Users] OrgA <---> Contract OrgB <---> Contract Contract --> Order Order --> Milestone --> Escrow Order --> Deliverable Order --> Payment --> Webhooks[(Provider Webhooks)] Order --> Dispute --> Reputation Order --> Invoice
Tenancy & data boundaries
Every request executes in a single-org context (the org in your session).
Cross-org operations require an active partner link and explicit consent flows.
Reports/exports never cross org boundaries unless both parties allow it.
Switching orgs
UI: Profile → Switch organization
API: log in to the desired org; the session cookie scopes calls.
Data residency: Org metadata includes region (for storage/invoices). Plan-based options available.
Edge cases:
A user in multiple orgs must switch contexts; there’s no “global” view.
Attempting cross-org without a partner link returns 403.
Roles & permissions (RBAC)
Owner — billing & policies; full access.
Admin — manage users, partner links, KYC, disputes; create/approve contracts.
Member — day-to-day execution: drafts, orders, deliverables.
Server guardrail
function requireRole(...roles: Array<'owner'|'admin'|'member'>) { return (req, res, next) => { if (!req.user) return res.status(401).json({ message: 'Auth required' }); if (!roles.includes(req.user.role)) return res.status(403).json({ message: 'Insufficient role' }); next(); }; }
Identifiers & references
Internal IDs:
org_123,usr_42,ct_987,ord_456,inv_1122.Always add a business-meaningful reference for idempotency & reconciliation.
Anti-patterns
Using emails as persistent IDs.
Storing PII in free-text fields (use structured fields).
QA checklist
Cross-org call without partner link ⇒ 403.
Member cannot access admin-only endpoints ⇒ 403.
Switching org changes visible contracts/orders accordingly.