docs: define organization account model

docs/FEATURES/organizations.md

@@ -0,0 +1,195 @@
+# 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.