Multi-Organization Architecture

Understanding multi-organization in ARSAKA PUGUH.

Overview

PUGUH uses a multi-organization architecture where each organization has completely isolated data and configuration. This enables:

• Data Isolation: Complete separation between organizations
• Configuration Independence: Each organization has its own settings and applications
• Resource Management: Per-organization billing and limits
• Security: No cross-organization data leakage

Organization Hierarchy

Organization
  Users (via Memberships)
    Owner (1 per organization)
    Admins
    Members
    Viewers

  Applications
    Production
    Staging
    Development

  Rules
    Organization-level (shared)
    Application-level (isolated)

  Workflows
    Application-scoped

  Subscription
    Plan + Billing

Data Isolation

Database Level

Every table includes organization_id:

CREATE TABLE rules (
  id UUID PRIMARY KEY,
  organization_id UUID NOT NULL,  -- Organization isolation
  application_id UUID,             -- Optional application scope
  name TEXT,
  ...
);

-- Row-Level Security (RLS) enforces isolation
CREATE POLICY organization_isolation ON rules
  USING (organization_id = current_setting('app.current_organization')::uuid);

API Level

All API requests are scoped to an organization:

GET /api/v1/rules
Authorization: Bearer {token}
X-Organization-ID: {organization_id}

The token contains organization membership information, and all queries are automatically filtered.

Application Level

// SDK automatically includes organization context
const client = new PuguhClient({
  organizationId: 'your-organization-id',
  // ...
});

// All operations scoped to this organization
const webhooks = await client.webhooks.list(); // Only returns organization's webhooks

Organization Membership

User-Organization Relationship

Users can belong to multiple organizations:

User: alice@example.com
  Organization: Acme Corp (Owner)
  Organization: Consulting Co (Admin)
  Organization: Partner Inc (Member)

Membership Model

interface OrganizationMembership {
  userId: string;
  organizationId: string;
  role: 'owner' | 'admin' | 'member' | 'viewer';
  status: 'active' | 'invited' | 'suspended';
  joinedAt: Date;
}

Switching Organizations

// List user's organizations
const organizations = await client.listMyOrganizations();

// Switch active organization
await client.setActiveOrganization(organizationId);

Application Scoping

Applications provide an additional isolation layer within organizations.

When to Use Applications

Resource Scoping

Resources are scoped at two levels:

1. Organization-level: Users, roles, billing, audit logs
2. Application-level: Webhooks, storage, API keys

// Organization-level: list all members
const members = await client.organizations.listMembers(orgId);

// Application-level: create a webhook for a specific app
await client.webhooks.create({
  url: 'https://prod.example.com/webhook',
  eventTypes: ['user.registered'],
  applicationId: 'prod-app-id',
});

Access Control

Access is managed at both levels:

1. Organization role determines base permissions
2. Application membership restricts resource access further
3. Organization Owners have access to all applications

Organization Limits

Each plan has organization-level limits:

Checking Limits

const usage = await client.getOrganizationUsage();

console.log(usage.storage.used);  // '2.5 GB'
console.log(usage.storage.limit); // '10 GB'
console.log(usage.members.used);  // 5
console.log(usage.members.limit); // 10

Limit Enforcement

When limits are exceeded:

• Storage: File uploads return 413 with upgrade prompt
• Applications: Cannot create new applications
• Users: Cannot invite new members

Cross-Organization Operations

Cross-organization operations are not allowed by design:

• Users cannot access other organizations' data
• API keys are organization-scoped
• No cross-organization queries possible

Shared Resources (Enterprise)

Enterprise customers can set up controlled sharing:

1. Service Organizations: Shared services across organizations
2. Federation: Connect multiple organizations
3. Data Sync: Controlled replication

Contact support for enterprise features.

Security Considerations

Organization Isolation Guarantees

1. Query Isolation: All queries filtered by organization_id
2. Index Separation: Organization-scoped indexes
3. Encryption: Per-organization encryption keys (Enterprise)
4. Audit Isolation: Organization-specific audit logs

Security Best Practices

1. Use Application Separation: Separate sensitive data in applications
2. Regular Access Review: Audit organization memberships
3. Minimal Permissions: Use least privilege principle
4. Monitor Cross-Organization: Watch for anomalies

Migration Between Organizations

Moving Resources

Resources cannot be moved between organizations directly. To migrate:

1. Export from source organization
2. Import to destination organization
3. Verify and validate
4. Delete from source

Export/Import

# Export rules
puguh-cli export rules --organization SOURCE_ORG --output rules.json

# Import to new organization
puguh-cli import rules --organization DEST_ORG --input rules.json

Troubleshooting

"Organization not found"

• Verify organization ID is correct
• Check user has access to organization
• Ensure organization is not suspended

"Cross-organization access denied"

• Cannot access resources from another organization
• Switch to correct organization first
• Verify membership status

"Limit exceeded"

• Check current usage vs limits
• Upgrade plan or reduce usage
• Contact support for temporary increase

Related

• Resource Scoping
• Best Practices
• Troubleshooting