# Feature: Organizations

## Status

Ready for initial backend implementation.

## 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.

## Implementation Readiness

The initial implementation should proceed through the task files in `docs/TASKS/organizations/`.

Recommended order:

1. `001-organization-domain-foundation.md`
2. `002-organization-membership-permissions.md`
3. `003-organization-settings-ui.md`
4. `004-workspace-selector-organization-switcher.md`

Task 001 should establish the organization table, workspace ownership, current-user organization read APIs, and development bootstrap data. It should not attempt the full inherited permission model beyond enough access data to prove a user can access their organizations.

Task 002 should introduce organization memberships and explicit organization permissions before frontend settings or switcher work relies on permission-gated data.

Frontend tasks should start only after backend contracts have been regenerated into `shared/openapi/openapi.json` and `frontend/src/api/schema.d.ts`.

Initial backend routes:

```txt
GET /api/organizations
GET /api/organizations/{organizationId}
```

Workspace responses should include `organizationId` once workspaces are owned by organizations.

## 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.
