222 lines
8.3 KiB
Markdown
222 lines
8.3 KiB
Markdown
# 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.
|