User Workflow Architecture
Executive Summary
This document maps all user personas and their workflows through the CODITECT platform, from single individual developers to enterprise organizations with consultants and auditors accessing multiple tenants.
Critical Path Impact: This architecture directly affects A.11 (Workstation Broker), A.12 (Team Management), and the RBAC system.
Table of Contents
- User Personas
- Entity Hierarchy Mapping
- Workflow Matrices
- Cross-Tenant Access Patterns
- Implementation Requirements
1. User Personas
1.1 Single User (Individual Developer)
┌─────────────────────────────────────────────────────────────────┐
│ PERSONA: Single User (Freelancer/Solo Developer) │
├─────────────────────────────────────────────────────────────────┤
│ Account Type: Individual │
│ License Tier: Free / Pro │
│ Entity Level: User (no org/team hierarchy) │
│ Max Workstations: 1 (Free) / 3 (Pro) │
│ Context Scope: Personal only │
└─────────────────────────────────────────────────────────────────┘
Journey:
Register → Verify Email → Choose Plan → Provision Workstation → Start Coding
Access Pattern:
- Creates personal "individual" organization automatically
- All resources owned directly by user
- No team/invitation capabilities on Free tier
- Can upgrade to Team tier to invite collaborators
Database Model:
-- Implicit organization created on registration
INSERT INTO organizations (id, name, type, owner_id, tier)
VALUES (uuid, 'john-doe-personal', 'individual', user_id, 'free');
1.2 Small Team (2-10 Users)
┌─────────────────────────────────────────────────────────────────┐
│ PERSONA: Small Team (Startup/Agency) │
├─────────────────────────────────────────────────────────────────┤
│ Account Type: Team │
│ License Tier: Starter / Professional │
│ Entity Level: Organization → Team → User │
│ Max Members: 5 (Starter) / 20 (Professional) │
│ Workstations: 1 per user │
│ Context Scope: Team-shared │
└─────────────────────────────────────────────────────────────────┘
Journey (Founder):
Register → Create Organization → Choose Team Plan → Invite Members → Assign Roles
Journey (Invited Member):
Receive Invite → Accept → Set Password → Join Org → Get Workstation → Start Coding
Roles:
| Role | Can Invite | Can Manage Projects | Can Access Billing | Can Delete Org |
|---|---|---|---|---|
| Owner | ✅ | ✅ | ✅ | ✅ |
| Admin | ✅ | ✅ | ✅ | ❌ |
| Developer | ❌ | ✅ (assigned) | ❌ | ❌ |
| Viewer | ❌ | Read-only | ❌ | ❌ |
Workflow Reference: WF-005 (User Invitation)
1.3 Large Team / Enterprise (10-100+ Users)
┌─────────────────────────────────────────────────────────────────┐
│ PERSONA: Enterprise Team (Department/Division) │
├─────────────────────────────────────────────────────────────────┤
│ Account Type: Company / Enterprise │
│ License Tier: Business / Enterprise │
│ Entity Level: Org → LegalEntity → OpUnit → Dept → Team → User │
│ Max Members: 100 (Business) / Unlimited (Enterprise) │
│ Features: SSO, Audit Logs, Custom RBAC │
│ Context Scope: Team + Project isolated │
└─────────────────────────────────────────────────────────────────┘
Journey (IT Admin):
SSO Setup → SCIM Provisioning → Configure Teams → Set Permissions → Bulk Invite
Journey (Developer):
SSO Login → Auto-Provisioned → Assigned to Team → Get Workstation → Access Projects
Multi-Team Structure:
Acme Corp (Organization)
├── Engineering (Department)
│ ├── Platform Team (Team)
│ │ ├── alice@acme.com (Lead)
│ │ └── bob@acme.com (Developer)
│ └── Frontend Team (Team)
│ ├── carol@acme.com (Lead)
│ └── dave@acme.com (Developer)
└── Data Science (Department)
└── ML Team (Team)
└── eve@acme.com (Data Scientist)
License Allocation:
- Organization purchases N seats
- Seats distributed across teams
- Admin dashboard shows utilization per team
- Over-allocation blocked (cannot assign more than purchased)
1.4 Consultant / Contractor (Multi-Tenant Access)
┌─────────────────────────────────────────────────────────────────┐
│ PERSONA: Consultant (Works Across Multiple Clients) │
├─────────────────────────────────────────────────────────────────┤
│ Account Type: Individual (with client invitations) │
│ Access Pattern: Invited to multiple orgs as 'contractor' │
│ Identity: Single identity, multiple org memberships │
│ Context Scope: Org-isolated (switches between clients) │
│ Time Bounds: Optional project-based expiration │
└─────────────────────────────────────────────────────────────────┘
Journey:
Has Personal Account → Client A Invites as Contractor → Client B Invites →
Switches Context Between Clients → Time-Limited Access Expires
Database Model:
-- Single user with multiple org memberships
CREATE TABLE organization_memberships (
id UUID PRIMARY KEY,
user_id UUID REFERENCES users(id),
organization_id UUID REFERENCES organizations(id),
role VARCHAR(50), -- 'contractor'
expires_at TIMESTAMP, -- Time-limited
project_ids UUID[], -- Scoped to specific projects
created_at TIMESTAMP,
invited_by UUID REFERENCES users(id)
);
-- Consultant's memberships
user: consultant@example.com
├── org: client-a.acme.com (contractor, expires: 2026-03-31)
├── org: client-b.bigco.com (contractor, expires: 2026-06-30)
└── org: personal-workspace (owner, no expiry)
Context Switching UI:
┌─────────────────────────────────────────────────────────────────┐
│ Current Workspace: [▼ Client A - Acme Corp] │
│ ───────────────────────────────────────── │
│ • Client A - Acme Corp (contractor) - expires Mar 31 │
│ • Client B - BigCo (contractor) - expires Jun 30 │
│ • Personal Workspace (owner) │
└─────────────────────────────────────────────────────────────────┘
Critical Implementation Notes:
- Single Identity: User has ONE account, multiple memberships
- License Attribution: Contractor uses CLIENT's seat, not their own
- Data Isolation: When in Client A context, cannot see Client B data
- Audit Trail: All actions logged with org context
1.5 Multi-Tenant Organization (Agency/Holding Company)
┌─────────────────────────────────────────────────────────────────┐
│ PERSONA: Agency Managing Multiple Client Tenants │
├─────────────────────────────────────────────────────────────────┤
│ Account Type: Multi-Subsidiary / White-Label Partner │
│ Entity Level: Platform → Org → Multiple Child Orgs │
│ Pattern: Parent org with visibility into child orgs │
│ Use Case: Dev agency, MSP, consulting firm │
│ Billing: Consolidated or per-client │
└─────────────────────────────────────────────────────────────────┘
Structure:
DevAgency (Parent Organization)
├── Client: Startup-X (Child Org - managed tenant)
│ ├── dev1@devagency.com (admin, from parent)
│ └── founder@startupx.com (owner, client's user)
├── Client: Retailer-Y (Child Org - managed tenant)
│ ├── dev2@devagency.com (admin, from parent)
│ └── cto@retailery.com (owner, client's user)
└── Internal Projects (Child Org - agency's own)
└── team@devagency.com
Access Pattern:
Agency Admin can:
├── Create/delete client tenants
├── Add agency staff to client tenants
├── View consolidated reporting across all clients
├── Cannot see client data without explicit assignment
└── Bill clients directly or consolidated through agency
Database Model:
-- Parent-child org relationships
CREATE TABLE organization_relationships (
id UUID PRIMARY KEY,
parent_org_id UUID REFERENCES organizations(id),
child_org_id UUID REFERENCES organizations(id),
relationship_type VARCHAR(50), -- 'managed_tenant', 'subsidiary', 'joint_venture'
ownership_percentage DECIMAL(5,2),
billing_model VARCHAR(50), -- 'consolidated', 'direct', 'passthrough'
created_at TIMESTAMP
);
1.6 Auditor (External Compliance Access)
┌─────────────────────────────────────────────────────────────────┐
│ PERSONA: External Auditor (SOC 2, ISO 27001, GDPR) │
├─────────────────────────────────────────────────────────────────┤
│ Account Type: Auditor Access (not a full user) │
│ Access Pattern: Time-limited, scoped, read-only │
│ Duration: 1-90 days (default 30) │
│ Data Access: Scoped by audit type │
│ Actions: View + Export only │
└─────────────────────────────────────────────────────────────────┘
Scopes (from WF-006):
| Scope | Resources | Use Case |
|---|---|---|
| security | audit_logs, access_reports, security_config | Pen test review |
| financial | billing_history, invoices, usage_reports | SOX compliance |
| compliance | audit_logs, compliance_status, user_activity, access_reports | SOC 2, ISO 27001 |
| full | All resources | Annual comprehensive audit |
Journey:
Org Owner grants access → Auditor receives email →
Auditor logs in with token → Views scoped dashboard →
Exports evidence → Access auto-expires
Workflow Reference: WF-006 (Auditor Access Grant)
Key Difference from Consultant:
- Auditor: NO account in system, token-based temporary access
- Consultant: HAS account, invited as contractor role
1.7 Developer with Multi-Tenant Access (Enterprise Scenario)
┌─────────────────────────────────────────────────────────────────┐
│ PERSONA: Enterprise Dev with Access to Multiple Business Units │
├─────────────────────────────────────────────────────────────────┤
│ Account Type: Enterprise User │
│ Access Pattern: SSO, assigned to multiple OpUnits/Teams │
│ Context: Can access projects across business units │
│ Use Case: Shared services, platform teams │
│ Permissions: Role varies by context (admin in A, dev in B) │
└─────────────────────────────────────────────────────────────────┘
Structure (ADR-047 6-level hierarchy):
Global Corp (Organization)
├── Legal Entity: GlobalCorp US LLC
│ ├── Operating Unit: Consumer Products
│ │ └── Platform Team → alice (admin)
│ └── Operating Unit: B2B Services
│ └── Platform Team → alice (developer)
└── Legal Entity: GlobalCorp EU GmbH
└── Operating Unit: EU Operations
└── Platform Team → alice (viewer)
Permission Resolution:
def get_user_permission(user, resource):
# Find most specific role for resource's context
context_chain = [resource.team, resource.dept, resource.opunit,
resource.legal_entity, resource.org]
for context in context_chain:
if role := user.get_role_in(context):
return role.permissions
return DENIED
2. Entity Hierarchy Mapping
2.1 Full ADR-047 Hierarchy
┌─────────────────────────────────────────────────────────────────────────────┐
│ CODITECT ENTITY HIERARCHY │
│ (ADR-047 Reference) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Level 0: PLATFORM (White-Label Instance) │
│ │ ├── coditect.ai (primary) │
│ │ └── partner.customdev.io (white-label) │
│ │ │
│ ▼ │
│ Level 1: ORGANIZATION (Subscriber/Customer Account) │
│ │ ├── Individual: john-doe-personal │
│ │ ├── Team: startup-abc │
│ │ ├── Company: acme-corp │
│ │ ├── Enterprise: global-megacorp │
│ │ └── Multi-Subsidiary: holding-group │
│ │ │
│ ▼ │
│ Level 2: LEGAL ENTITY (Tax ID, Jurisdiction) │
│ │ ├── Acme Corp US LLC (EIN: 12-3456789) │
│ │ ├── Acme Corp UK Ltd (Company: 12345678) │
│ │ └── Acme Corp GmbH (HRB: 123456) │
│ │ │
│ ▼ │
│ Level 3: OPERATING UNIT (P&L Responsibility) │
│ │ ├── Consumer Products Division │
│ │ ├── Enterprise Solutions Division │
│ │ └── Shared Services │
│ │ │
│ ▼ │
│ Level 4: DEPARTMENT (Cost Center) │
│ │ ├── Engineering │
│ │ ├── Product │
│ │ └── Data Science │
│ │ │
│ ▼ │
│ Level 5: TEAM (Collaborative Work Group) │
│ │ ├── Platform Team │
│ │ ├── Frontend Team │
│ │ └── ML Team │
│ │ │
│ ▼ │
│ Level 6: USER (Individual with Role-Based Access) │
│ ├── alice@acme.com (Lead, Platform Team) │
│ ├── bob@acme.com (Developer, Platform Team) │
│ └── auditor@kpmg.com (Auditor Access, temp) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
2.2 Persona → Entity Level Mapping
| Persona | Org Type | Uses Levels | License Seat | Example |
|---|---|---|---|---|
| Single User | Individual | 1 (Org=User) | 1 (self) | Freelancer |
| Small Team | Team | 1-5 (Org→Team→User) | Per member | Startup |
| Large Team | Company/Enterprise | 1-6 (full hierarchy) | Pool | Enterprise dept |
| Consultant | N/A (invited) | Joins at Level 5-6 | Client's seat | Agency dev |
| Agency | Multi-Subsidiary | 1-2 (Parent→Children) | Per client or consolidated | MSP |
| Auditor | N/A (token access) | Scoped access to data | None | KPMG auditor |
| Multi-OpUnit Dev | Enterprise | 1-6 with multiple L3-5 memberships | 1 (SSO user) | Platform team |
3. Workflow Matrices
3.1 License & Workstation Flow by Persona
┌─────────────────────────────────────────────────────────────────────────────┐
│ LICENSE → WORKSTATION FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ SINGLE USER: │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Buy License → License Provisioned → Workstation Auto-Created → │ │
│ │ → User Clicks "Launch IDE" → Working │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ SMALL TEAM (Owner): │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Buy N Seats → Seats Pool Created → Invite Team Members → │ │
│ │ → Each Member Gets Seat Assigned → Each Member Gets Workstation │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ SMALL TEAM (Invited Member): │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Receive Invite → Accept & Register → Seat Auto-Assigned → │ │
│ │ → Workstation Auto-Provisioned → Start Coding │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ CONSULTANT: │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Client Invites → Consultant Accepts → Uses CLIENT'S Seat → │ │
│ │ → Workstation in CLIENT'S Tenant → Access Expires │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ENTERPRISE (SSO/SCIM): │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ IT Buys N Seats → Configures SSO → User SSO Logins → │ │
│ │ → SCIM Auto-Provisions → Seat from Pool → Workstation Assigned │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
3.2 Access Control Matrix
| Action | Owner | Admin | Developer | Contractor | Viewer | Auditor |
|---|---|---|---|---|---|---|
| Organization | ||||||
| Create org | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Delete org | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Modify billing | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| View billing | ✅ | ✅ | ❌ | ❌ | ❌ | 📊 scope |
| Members | ||||||
| Invite members | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Remove members | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Grant auditor access | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Teams | ||||||
| Create team | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Assign to team | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Projects | ||||||
| Create project | ✅ | ✅ | ✅ | ⚙️ assigned | ❌ | ❌ |
| View project | ✅ | ✅ | ✅ | ⚙️ assigned | ✅ | 📊 scope |
| Delete project | ✅ | ✅ | ⚙️ own | ❌ | ❌ | ❌ |
| Workstations | ||||||
| Provision own | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| View all sessions | ✅ | ✅ | ❌ | ❌ | ❌ | 📊 scope |
| Terminate any | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Audit | ||||||
| View audit logs | ✅ | ✅ | ❌ | ❌ | ❌ | 📊 scope |
| Export audit logs | ✅ | ✅ | ❌ | ❌ | ❌ | 📊 scope |
Legend: ✅ = Yes | ❌ = No | ⚙️ = Conditional | 📊 = Scoped by audit type
4. Cross-Tenant Access Patterns
4.1 Single Identity, Multiple Tenants
┌─────────────────────┐
│ consultant@ex.com │
│ (Single Identity) │
└──────────┬──────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Client A │ │ Client B │ │ Personal │
│ (Acme Corp)│ │ (BigCo) │ │ Workspace │
├─────────────┤ ├─────────────┤ ├─────────────┤
│ Role: contr │ │ Role: contr │ │ Role: owner │
│ Expires: 3mo│ │ Expires: 6mo│ │ No expiry │
│ Projects: 2 │ │ Projects: 1 │ │ Projects: * │
└─────────────┘ └─────────────┘ └─────────────┘
DATA ISOLATION: When consultant is in "Client A" context,
Client B and Personal data are completely invisible.
4.2 Agency Model (Parent-Child Tenants)
┌─────────────────────────────┐
│ DevAgency (Parent) │
│ Billing: Consolidated │
├─────────────────────────────┤
│ agency-admin@devagency.com │
│ agency-dev1@devagency.com │
│ agency-dev2@devagency.com │
└──────────────┬──────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Client: X │ │ Client: Y │ │ Internal │
│ (Managed) │ │ (Managed) │ │ Projects │
├─────────────────┤ ├─────────────────┤ ├─────────────────┤
│ From Parent: │ │ From Parent: │ │ From Parent: │
│ • agency-dev1 │ │ • agency-dev2 │ │ • agency-admin │
│ (admin) │ │ (admin) │ │ (owner) │
│ │ │ │ │ │
│ Client's Users: │ │ Client's Users: │ │ Agency Users: │
│ • founder@x.com │ │ • cto@y.com │ │ • all staff │
│ (owner) │ │ (owner) │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
VISIBILITY: agency-admin can see consolidated metrics across all
child tenants but cannot see project data without explicit assignment.
4.3 Auditor Access Pattern
┌─────────────────────────────┐
│ auditor@kpmg.com │
│ (Token-Based, No Account) │
└──────────────┬──────────────┘
│
│ Token: abc123...
│ Scope: compliance
│ Expires: 30 days
│
▼
┌─────────────────────────────┐
│ Auditor Dashboard │
│ (Read-Only View) │
├─────────────────────────────┤
│ ✅ audit_logs │
│ ✅ compliance_status │
│ ✅ user_activity │
│ ✅ access_reports │
│ ❌ billing (not in scope) │
│ ❌ project data (not in scope)│
└─────────────────────────────┘
ALL ACTIONS LOGGED with IP, timestamp, exported files
5. Implementation Requirements
5.1 Data Model Requirements
| Requirement | Model/Table | Track |
|---|---|---|
| Organization types | organizations.type enum | A.12 |
| Entity hierarchy | legal_entities, operating_units, departments | Future |
| Org relationships | organization_relationships | A.12 |
| Multi-org membership | organization_memberships with expires_at | A.12 |
| Contractor role | role='contractor' + expires_at + project_ids[] | A.12 |
| Auditor access | auditor_access table | Exists (WF-006) |
| Context switching | Current org in JWT claims | A.11/A.12 |
5.2 API Endpoint Requirements
| Endpoint | Purpose | Track |
|---|---|---|
POST /api/v1/organizations/ | Create org | A.12 |
GET /api/v1/organizations/ | List user's orgs | A.12 |
POST /api/v1/organizations/{id}/members/ | Invite member | A.12 (WF-005) |
DELETE /api/v1/organizations/{id}/members/{user_id}/ | Remove member | A.12 |
POST /api/v1/organizations/{id}/children/ | Create managed tenant | A.12 |
GET /api/v1/organizations/{id}/children/ | List child orgs | A.12 |
POST /api/v1/organizations/{id}/auditor-access/ | Grant auditor | Exists (WF-006) |
GET /api/v1/users/me/memberships/ | User's org memberships | A.12 |
PUT /api/v1/users/me/current-organization/ | Switch context | A.12 |
5.3 Frontend Requirements
| Component | Purpose | Track |
|---|---|---|
| OrgSwitcher | Dropdown to switch organization context | B.4 |
| MemberInviteForm | Invite with role & optional expiry | B.4 |
| ManagedTenantsList | Agency view of client tenants | B.4 |
| AuditorAccessGrant | Grant auditor access form | B.4 |
| TeamManagement | CRUD for teams within org | B.4 |
| SeatAllocation | Visual seat pool management | B.4 |
| MemberRoleEditor | Change member's role | B.4 |
5.4 Critical Path Impact
This workflow architecture directly impacts:
-
A.11 (Cloud Workstation Broker):
- Workstation provisioned in context of user's CURRENT organization
- License seat from that org's pool
- Consultant uses client's seat, not personal
-
A.12 (Team & License Management):
- Invitation flow with role assignment
- License seat allocation and tracking
- Organization hierarchy CRUD
-
B.4.5 (Container Session UI):
- Sessions filtered by org context
- Admin sees all sessions in their org
- Contractor sees only assigned projects
6. Open Questions
| Question | Impact | Decision Needed By |
|---|---|---|
| Can consultants have their own workstation, or only use client's? | A.11 architecture | Before A.11 implementation |
| Do we support "bring your own license" for contractors? | Billing model | Before A.12 implementation |
| Should agency admins have "super admin" across all children? | Security model | Before org relationships |
| How to handle consultant who needs simultaneous access to 2 clients? | Context model | Before A.12 implementation |
| Do auditors count against seat limits? | License model | Before billing integration |
Related Documents
- ADR-047: CODITECT-PLATFORM Foundation Architecture Discovery
- ADR-009: Multi-Tenant SaaS Architecture
- WF-005: User Invitation Workflow
- WF-006: Auditor Access Grant Workflow
- PILOT-PARALLEL-EXECUTION-PLAN.md - Tracks A.11, A.12
Version: 1.0.0 Created: January 5, 2026 Author: CODITECT Team