social-media/docs/FEATURES/organizations.md

Feature: Organizations

Status

Draft

Goal

Define the SaaS account boundary above workspaces.

An Organization owns billing, subscriptions, usage limits, organization-level users, connectors, data mappings, and the workspaces used for brand/client workflow.

User Stories

• As an agency owner, I want my company to own multiple brand workspaces so that billing and administration happen once.
• As an in-house brand team, I want my company to own its workspaces so that billing, users, and connectors are controlled centrally.
• As a professional user, I want one login that can access multiple organizations so that I can work for my employer and freelance clients from the same account.
• As an organization admin, I want to manage organization members so that company-level access can grant inherited workspace access.
• As an organization admin, I want external clients and collaborators to remain visible in workspace members without making them organization members.
• As a billing manager, I want to manage subscription and billing for the organization.
• As an organization admin, I want to configure connectors such as Google Drive once for the organization.
• As a workspace user, I want the existing workspace selector to stay central while still letting me switch organizations.

Domain Model

Organization

Organization is the SaaS account boundary.

An organization owns:

• billing profile
• subscription plan
• subscription limits
• organization-level users and roles
• workspaces
• connectors and integration credentials
• data mapping rules for connected systems

An organization can own many workspaces.

Workspace

Workspace is the brand/client workflow boundary.

Each workspace:

• belongs to exactly one organization
• is not shared between organizations
• owns brand/client content workflow data
• owns configured social channels
• uses organization-level connectors

Channel

Channel is a configured social destination inside a workspace, such as a Twitter/X account, YouTube channel, Facebook page, Instagram account, or newsletter destination.

Connector credentials for external systems are configured at the organization level in v1.

User

User is a global login identity.

A user can have access relationships with multiple organizations and direct access to multiple workspaces. A user account is not owned by a single organization.

Example:

alex@example.com
  -> Organization access: PepsiCo, Content Manager
  -> Organization access: Alex Freelance LLC, Owner and Billing Manager
  -> Workspace access: Client review workspace, External Reviewer

Membership And Access

Organization Membership

Organization membership grants organization-level permissions and inherited workspace permissions across all workspaces owned by the organization.

Organization-level permissions include:

• organization settings
• organization member management
• workspace creation and administration
• billing and subscription management
• connector and data mapping management

Only users with a billing manager permission can view or edit billing and subscription information.

Workspace Membership

Workspace membership grants access to one workspace.

Workspace participants have a relationship category relative to the organization that owns the workspace:

• Organization Member
• External Collaborator

Organization Member means the user is part of the owning organization. The user may have access through organization membership, direct workspace membership, or both.

External Collaborator means the user is not part of the owning organization but has direct workspace access. This includes subcontractors, providers, clients, and external reviewers.

External collaborators can be invited directly to a workspace without becoming organization members.

Organization admins should still be able to see external collaborators when reviewing who has access to organization-owned data.

Workspace membership can override applicable inherited workspace permissions. Organization-only permissions such as billing are not overridden at the workspace level.

Permission Rules

• Organization permissions are inherited by all owned workspaces when they apply to workspace behavior.
• Workspace-level overrides can reduce or expand workspace-specific permissions where that makes sense.
• Billing and subscription permissions live only at the organization level.
• Connector management lives only at the organization level in v1.
• External collaborators cannot access organization billing, subscription, or connector settings unless they are separately granted organization membership with those permissions.

Connectors And Data Mappings

Connectors are configured only at the organization level in v1.

Examples:

• Google Drive connection
• connector credentials
• default Drive folder mapping rules
• organization-wide data import or linkage rules

Workspaces use organization-level connectors and mappings. Workspace-specific connector credentials are out of scope for v1.

Subscription And Limits

Subscription plans and usage limits belong to the organization.

Potential limits include:

• number of workspaces
• number of organization members
• number of external collaborators
• channels per workspace or per organization
• storage or asset limits
• access to advanced workflow features

Exact plan limits are a billing/product task and are not defined here.

Frontend Surface

The existing workspace selector remains the primary navigation context.

Add an organization switcher at the bottom of the workspace selector.

Organization settings use one explicit organization route:

/app/organizations/:organizationId/settings

The settings page should contain sections for:

• profile/settings
• members
• billing
• connections
• workspaces

Workspace-level screens remain centered on the selected workspace.

Backend Expectations

• Backend feature code should follow existing module patterns under backend/src/Socialize.Api/Modules.
• Workspaces must require an owning organization.
• Organization APIs should return only organizations the current user can access.
• Workspace APIs must preserve workspace scoping and account for inherited organization permissions.
• New backend contracts require OpenAPI regeneration while the backend is running.

Out Of Scope For Initial Implementation

• Preserving existing local data through migration. Development data can be wiped.
• Workspace sharing across organizations.
• Workspace-level connector credentials.
• Full billing provider integration.
• Final subscription packaging and pricing.
• Cross-organization workspace access inheritance.

Done When

• Organization is documented as the SaaS account boundary.
• Workspace is documented as the brand/client workflow boundary.
• Workspaces belong to exactly one organization.
• Organization membership can grant inherited workspace access.
• Workspace membership supports direct access and overrides.
• External collaborators do not require organization membership.
• Billing permissions live at the organization level.
• Connectors and data mappings live at the organization level.
• The workspace selector includes an organization switcher.