Workspace Documentation

The Workspace provides organisation hierarchy, asset management, and scoped access control for your enterprise AI infrastructure.

What is the Workspace?

The Workspace is your enterprise command centre within Quox. It organises everything into a clear hierarchy and lets you manage AI tools, workflows, and assistants with proper access controls.

In simple terms: Think of the Workspace like a company building. The company (Organisation) has floors (Divisions), departments on each floor, and teams within departments. The Workspace helps you organise who can see and use what.

Why do you need a workspace?

As your AI infrastructure grows, you need structure:

Organisation - Keep tools and assistants organised by team/department
Access Control - Share the right things with the right people
Asset Management - Track all your AI tools, workflows, and assistants in one place
Scope-based Views - See only what's relevant to your current context

Key concepts explained

Term	What it means
Organisation	Your company or top-level group
Division	Major unit within an org (like "Engineering" or "Operations")
Department	Sub-unit within a division (like "Backend Team" or "DevOps")
Team	Working group of people
Scope	A "lens" that filters what you see based on where you are in the hierarchy
Share Policy	Rules for who can see an asset (private, team-only, org-wide, etc.)

What can you manage?

Asset Type	What It Is
Tools	Individual capabilities agents can use (MCP servers, APIs, scripts)
Workflows	Multi-step automations that chain tools together
Assistants	AI personas with specific knowledge and capabilities
Tags	Labels to categorize and find assets easily

The scope system

The scope system is like a filter for your view:

Select a scope from the dropdown (org, division, department, or team)
See relevant assets - only items visible at that scope level appear
Navigate the hierarchy - use breadcrumbs to move up and down

Example: If you're in the "DevOps Team" scope, you'll see tools shared with your team, your department, your division, and org-wide tools. You won't see tools that are private to other teams.

Control who sees your assets:

Policy	Who Can See
Private	Only you (the creator)
Team	Your team members
Department	Everyone in your department
Division	Everyone in your division
Org-Wide	Everyone in the organisation
Explicit	Specific users/teams you choose

Phase B: Organization Model + Directory - Complete

Completed: 2026-01-21 Version: 1.0

Overview

Phase B transforms the basic auth system (Phase A/A.5) into a fully-scoped enterprise workspace with:

Organizational hierarchy (org → division → department → team)
Unified scope system for access control
Asset registry (tools, workflows, assistants)
Share policies for visibility control
Frontend workspace shell

Database Schema (schema-b1.sql)

New Tables

Table	Purpose
`divisions`	Top-level org units below org
`departments`	Units within divisions
`scopes`	Unified hierarchy tree with materialized paths
`scope_policies`	Policy overrides per scope
`share_policies`	Visibility rules (private/team/org/explicit)
`tools`	Tool definitions with specs
`tool_versions`	Version history for tools
`workflows`	Multi-step automations
`workflow_steps`	Individual steps in workflows
`workflow_versions`	Version history for workflows
`assistants`	AI persona definitions
`assistant_deployments`	Where assistants are deployed
`assistant_versions`	Version history for assistants
`tags`	Asset categorization
`asset_tags`	Tag assignments to assets
`user_favorites`	User bookmarks
`user_recent`	Recently accessed assets
`directory_index`	Full-text search index

Modified Tables

teams - Added attach_scope_id for scope attachment

API Endpoints

Divisions (`routes/divisions.js`)

GET    /api/orgs/:orgId/divisions           List divisions
POST   /api/orgs/:orgId/divisions           Create division
GET    /api/orgs/:orgId/divisions/:id       Get division
PATCH  /api/orgs/:orgId/divisions/:id       Update division
DELETE /api/orgs/:orgId/divisions/:id       Delete division

Departments (`routes/departments.js`)

GET    /api/orgs/:orgId/divisions/:divId/departments    List in division
POST   /api/orgs/:orgId/divisions/:divId/departments    Create department
GET    /api/orgs/:orgId/departments                     List all (flat)
GET    /api/orgs/:orgId/departments/:id                 Get department
PATCH  /api/orgs/:orgId/departments/:id                 Update department
DELETE /api/orgs/:orgId/departments/:id                 Delete department

Teams (`routes/teams.js`)

GET    /api/orgs/:orgId/teams               List teams
POST   /api/orgs/:orgId/teams               Create team
GET    /api/orgs/:orgId/teams/:id           Get team
PATCH  /api/orgs/:orgId/teams/:id           Update team
DELETE /api/orgs/:orgId/teams/:id           Delete team
GET    /api/orgs/:orgId/teams/:id/members   List members
POST   /api/orgs/:orgId/teams/:id/members   Add member
PATCH  /api/orgs/:orgId/teams/:id/members/:uid  Update member role
DELETE /api/orgs/:orgId/teams/:id/members/:uid  Remove member
GET    /api/orgs/:orgId/my-teams            User's teams

Scopes (`routes/scopes.js`)

GET    /api/orgs/:orgId/scopes              Get scope tree
GET    /api/orgs/:orgId/scopes/:id          Get scope details
GET    /api/orgs/:orgId/scopes/:id/path     Get breadcrumb path
GET    /api/orgs/:orgId/scopes/:id/children Get direct children
GET    /api/orgs/:orgId/scopes/:id/descendants  Get all descendants
GET    /api/orgs/:orgId/my-scopes           User's accessible scopes
GET    /api/orgs/:orgId/scope-by-entity     Get scope for entity

Share Policies (`routes/share-policies.js`)

GET    /api/orgs/:orgId/share-policies      List policies
POST   /api/orgs/:orgId/share-policies      Create policy
GET    /api/orgs/:orgId/share-policies/:id  Get policy
PATCH  /api/orgs/:orgId/share-policies/:id  Update policy
DELETE /api/orgs/:orgId/share-policies/:id  Delete policy
POST   /api/orgs/:orgId/share-policies/init-system  Initialize defaults

Policy Modes: private, team, department, division, org, explicit

Tools (`routes/tools.js`)

GET    /api/orgs/:orgId/tools               List tools
POST   /api/orgs/:orgId/tools               Create tool
GET    /api/orgs/:orgId/tools/:id           Get tool
PATCH  /api/orgs/:orgId/tools/:id           Update tool
DELETE /api/orgs/:orgId/tools/:id           Delete tool
POST   /api/orgs/:orgId/tools/:id/publish   Publish draft
POST   /api/orgs/:orgId/tools/:id/tags      Add tag
DELETE /api/orgs/:orgId/tools/:id/tags/:tagId  Remove tag
GET    /api/orgs/:orgId/tools/:id/versions/:v   Get version

Tool Types: mcp, function, api, script, workflow Risk Levels: low, medium, high, critical

Workflows (`routes/workflows.js`)

GET    /api/orgs/:orgId/workflows           List workflows
POST   /api/orgs/:orgId/workflows           Create workflow
GET    /api/orgs/:orgId/workflows/:id       Get workflow
PATCH  /api/orgs/:orgId/workflows/:id       Update workflow
DELETE /api/orgs/:orgId/workflows/:id       Delete workflow
POST   /api/orgs/:orgId/workflows/:id/publish   Publish draft
PUT    /api/orgs/:orgId/workflows/:id/steps     Replace steps
POST   /api/orgs/:orgId/workflows/:id/tags      Add tag
DELETE /api/orgs/:orgId/workflows/:id/tags/:tagId  Remove tag
GET    /api/orgs/:orgId/workflows/:id/versions/:v  Get version

Step Types: tool, condition, loop, parallel, wait, notify, transform

Assistants (`routes/assistants.js`)

GET    /api/orgs/:orgId/assistants          List assistants
POST   /api/orgs/:orgId/assistants          Create assistant
GET    /api/orgs/:orgId/assistants/:id      Get assistant
PATCH  /api/orgs/:orgId/assistants/:id      Update assistant
DELETE /api/orgs/:orgId/assistants/:id      Delete assistant
POST   /api/orgs/:orgId/assistants/:id/publish   Publish draft
POST   /api/orgs/:orgId/assistants/:id/deploy    Deploy to scope
PATCH  /api/orgs/:orgId/assistants/:id/deployments/:did  Update deployment
DELETE /api/orgs/:orgId/assistants/:id/deployments/:did  Remove deployment
POST   /api/orgs/:orgId/assistants/:id/fork      Fork assistant
POST   /api/orgs/:orgId/assistants/:id/tags      Add tag
DELETE /api/orgs/:orgId/assistants/:id/tags/:tagId  Remove tag
GET    /api/orgs/:orgId/assistants/:id/versions/:v  Get version
GET    /api/orgs/:orgId/available-assistants    Assistants in scope

Deployment Modes: private, shared, public

Tags (`routes/tags.js`)

GET    /api/orgs/:orgId/tags                List tags
POST   /api/orgs/:orgId/tags                Create tag
GET    /api/orgs/:orgId/tags/:id            Get tag
PATCH  /api/orgs/:orgId/tags/:id            Update tag
DELETE /api/orgs/:orgId/tags/:id            Delete tag

New Capabilities

Added to utils/policy.js:

Capability	Description
`org.manage_divisions`	Create/edit/delete divisions
`org.manage_departments`	Create/edit/delete departments
`directory.view`	View directory and assets
`directory.search`	Search directory
`directory.share`	Share assets with others
`share_policies.manage`	Manage share policies
`share_policies.view`	View share policies
`tags.manage`	Create/edit/delete tags
`tags.view`	View tags

Utility Modules

`utils/scopes.js`

Scope tree management with materialized paths:

createScope(orgId, type, refId, parentScopeId) - Create scope with auto path
getScopeById(scopeId) - Get scope
getScopePath(scopeId) - Get breadcrumb array
getScopeAncestors(scopeId) - Get ancestor chain
getScopeDescendants(scopeId) - Get all children recursively
getScopeTree(orgId) - Get full nested tree
resolveScopePolicy(scopeId) - Merge policies up chain
canAccessScope(userId, scopeId) - Check membership access
getUserAccessibleScopes(userId, orgId) - List user's scopes
getScopeForEntity(type, refId) - Find scope by entity
updateScopeName(scopeId, newName) - Update cached name
deleteScope(scopeId) - Soft delete with children
moveScope(scopeId, newParentId) - Relocate in tree

`utils/helpers.js`

Common utilities:

ulid() - Generate ULID
createAuditEvent(options) - Log to audit_events
slugify(text) - Convert to URL-safe slug
safeJsonParse(str, fallback) - Safe JSON parse
getPagination(page, limit) - Parse pagination params
formatPaginatedResponse(items, total, pagination) - Format response
isValidEmail(email) - Email validation
generateToken(length) - Secure random token
sha256(data) - Hash function

`utils/policy.js` Updates

evaluateSharePolicy(userId, asset, orgId) - Check share policy access
canAccessAsset(principal, asset, orgId) - Full asset access check

Frontend Structure

Contexts

File	Purpose
`contexts/AuthContext.jsx`	Auth state, login/logout, token refresh
`contexts/WorkspaceContext.jsx`	Org/scope selection, workspace state

Components (`components/workspace/`)

Component	Purpose
`OrgSelector`	Dropdown to switch organizations
`ScopePicker`	Tree dropdown to select scope lens
`ScopeBreadcrumb`	Current scope path navigation
`WorkspaceSidebar`	Main navigation sidebar
`workspace.css`	All workspace styling

Pages (`pages/workspace/`)

Page	Route	Status
`WorkspaceLayout`	`/workspace`	Layout wrapper
`WorkspaceOverview`	`/workspace`	Dashboard with stats
`DirectoryPage`	`/workspace/directory`	Universal search
`ToolsPage`	`/workspace/tools`	Tool list/management
`WorkflowsPage`	`/workspace/workflows`	Placeholder
`AssistantsPage`	`/workspace/assistants`	Placeholder
`DivisionsPage`	`/workspace/divisions`	Placeholder
`TeamsPage`	`/workspace/teams`	Placeholder
`MembersPage`	`/workspace/members`	Placeholder
`SettingsPage`	`/workspace/settings`	Placeholder
`AuditPage`	`/workspace/audit`	Placeholder

Auth Page

Page	Route
`LoginPage`	`/login`

File Summary

Backend (services/auth/)

db/schema-b1.sql          # New tables
db/index.js               # Migration logic (modified)
utils/scopes.js           # Scope utilities (new)
utils/helpers.js          # Common helpers (new)
utils/policy.js           # Added capabilities + asset access (modified)
routes/divisions.js       # Division CRUD (new)
routes/departments.js     # Department CRUD (new)
routes/teams.js           # Team management (new)
routes/scopes.js          # Scope navigation (new)
routes/share-policies.js  # Share policies (new)
routes/tools.js           # Tool assets (new)
routes/workflows.js       # Workflow assets (new)
routes/assistants.js      # Assistant assets (new)
routes/tags.js            # Tag management (new)
server.js                 # Mount routes (modified)

Frontend (src/)

contexts/AuthContext.jsx        # Auth provider (new)
contexts/WorkspaceContext.jsx   # Workspace provider (new)
contexts/index.js               # Exports (new)
components/workspace/           # All workspace components (new)
pages/workspace/                # All workspace pages (new)
pages/LoginPage.jsx             # Login page (new)
App.jsx                         # Added routes + providers (modified)

What's Next (Phase B.2+)

Full page implementations - Complete placeholder pages
Asset editors - Tool/workflow/assistant create/edit forms
Deployment UI - Assistant deployment management
Directory search - Full-text search integration
Share policy UI - Policy assignment and visualization
Tag management UI - Tag CRUD and assignment

Testing

Backend syntax verified:

bash

node -c services/auth/server.js  # OK

Frontend build verified:

bash

npm run build  # OK - 496 modules, 16.7s

Phase B provides the foundation for a fully-scoped enterprise workspace with hierarchical organization, asset registry, and share policies.

Workspace Documentation

What is the Workspace?

Why do you need a workspace?

Key concepts explained

What can you manage?

The scope system

Share policies

Phase B: Organization Model + Directory - Complete

Overview

Database Schema (schema-b1.sql)

New Tables

Modified Tables

API Endpoints

Divisions (routes/divisions.js)

Departments (routes/departments.js)

Teams (routes/teams.js)

Scopes (routes/scopes.js)

Share Policies (routes/share-policies.js)

Tools (routes/tools.js)

Workflows (routes/workflows.js)

Assistants (routes/assistants.js)

Tags (routes/tags.js)