# Org, Workspace & RBAC Roadmap

> **Purpose:** Add a first-class tenant model for organizations, workspaces,
> teams, memberships, scoped roles, and admin governance.
>
> **Primary Surface:** `services/platform-service/`
>
> **Status:** Planned
>
> **Estimated Effort:** 3-4 weeks

---

## Why This Is Missing

The platform has users and per-product memberships, but no canonical model for:

- organizations
- workspaces
- teams
- workspace-scoped roles
- resource ownership and sharing

Enterprise IdP support exists, but it does not replace a real tenant model.

---

## Recommended Stack

### Best Long-Term Industry Standard

- **PostgreSQL**
- **Drizzle ORM** or **Prisma**
- **OpenFGA** or Zanzibar-style authorization model for fine-grained access

### Best Repo-Fit Option

- `platform-service` module set backed by Cosmos
- Role and membership evaluation in service code
- Optional policy layer later using OpenFGA

### Recommendation

If tenanting will be central to the business, PostgreSQL is the better long-term
fit because org/workspace membership is relational by nature. If short-term
consistency matters more, start in Cosmos but keep the permission model portable.

### Default Decision For This Repo

- Keep auth identity in `platform-service`
- Add org/workspace/team as first-class platform modules
- Start with service-level authorization helpers
- Reserve OpenFGA for phase 2+ if sharing rules become too rich for code-level RBAC

---

## Dependencies

- None for the first schema pass
- Required by Knowledge & RAG, Human Review, AI Budgets, and SCIM

---

## V1 Non-Goals

- Full ABAC across every existing module
- End-user custom roles
- Cross-product federation of every resource type on day one

---

## Phase 1 - Data Model

- [ ] Create modules:
  - [ ] `orgs`
  - [ ] `workspaces`
  - [ ] `teams`
  - [ ] `memberships`
  - [ ] `roles`
- [ ] Define resources:
  - [ ] organization
  - [ ] workspace
  - [ ] team
  - [ ] service account
  - [ ] API key
- [ ] Define roles:
  - [ ] `org_owner`
  - [ ] `org_admin`
  - [ ] `workspace_admin`
  - [ ] `workspace_editor`
  - [ ] `workspace_viewer`
  - [ ] `support_operator`
- [ ] Add invitation and deprovision flows

**Acceptance Criteria**

- Every protected resource can be tied to org/workspace ownership
- Users can belong to multiple workspaces with different roles

---

## Phase 2 - Authorization

- [ ] Add authorization helpers to `@bytelyst/auth` or a new `@bytelyst/authorization`
- [ ] Evaluate permissions by resource and action
- [ ] Add policy checks for:
  - [ ] read
  - [ ] write
  - [ ] execute
  - [ ] approve
  - [ ] administer
- [ ] Add service account and API key scopes

**Acceptance Criteria**

- Endpoints no longer rely only on flat `admin` vs `user`
- Policies are testable and reusable across modules

---

## Phase 3 - Product Integration

- [ ] Migrate existing modules that should be workspace-scoped
- [ ] Add workspace headers or explicit route scoping
- [ ] Connect enterprise IdP claims to org/workspace resolution
- [ ] Add audit entries for membership and role changes

---

## Tech Stack Options

| Option                      | Pros                                | Cons                             | Fit                    |
| --------------------------- | ----------------------------------- | -------------------------------- | ---------------------- |
| PostgreSQL + OpenFGA        | Best long-term for RBAC and sharing | New datastore + auth layer       | Best industry-standard |
| PostgreSQL only             | Simpler than OpenFGA, still strong  | Fine-grained auth gets custom    | Good medium path       |
| Cosmos + service-level RBAC | Lowest disruption                   | Harder joins and policy richness | Good short-term        |

---

## Risks

- Flat roles will become a blocker for enterprise and multi-agent collaboration
- Delaying workspace boundaries causes later data migrations
- Fine-grained sharing is hard to retrofit once data models hardcode user ownership
