# 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: ```txt 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: ```txt /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.