Teams

Teams are working groups within your organisation. They have dedicated members, inboxes, and AI assistants for domain-specific collaboration.

What are Teams?

Teams are the smallest organisational unit in Quox. They represent working groups of people who collaborate on specific tasks, projects, or domains.

In simple terms: A team is like a project group. Team members can share an inbox, have a dedicated AI assistant, and manage resources specific to their work.

Team features

Team roles

Teams have their own role system separate from organisation roles:

Managing teams

Creating a team

1. Navigate to Teams from the sidebar
2. Click Create Team
3. Enter a name and optional description
4. Optionally attach to a division or department scope
5. You become the team admin

Adding members

1. Go to your team's management page
2. Click Add Member in the Members section
3. Select a user from your organisation
4. Choose a role (Admin, Member, or Viewer)

Team inbox

Each team can have its own inbox for:

• Approval requests routed to the team
• Tasks assigned to team members
• Alerts and notifications

API reference

Endpoints

Create team

curl -X POST /api/orgs/<orgId>/teams \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "API Team", "slug": "api-team", "description": "Backend API development"}'

Add team member

curl -X POST /api/orgs/<orgId>/teams/<teamId>/members \
  -H "Authorization: Bearer <token>" \
  -d '{"user_id": "<userId>", "role": "member"}'

Get my teams

curl /api/orgs/<orgId>/my-teams \
  -H "Authorization: Bearer <token>"

Returns teams where the current user is a member, including their role in each team.

Frontend implementation

Components

Routes

<Route path="/teams" element={<TeamsView />} />
<Route path="/teams/:teamId" element={<TeamManagementView />} />

Context

import { useWorkspace } from '../../contexts/WorkspaceContext'

const {
  getTeams,           // Fetch teams for org
  createTeam,         // Create new team
  updateTeam,         // Update team details
  deleteTeam,         // Delete team
  addTeamMember,      // Add member to team
  updateTeamMemberRole, // Change member role
  removeTeamMember    // Remove member from team
} = useWorkspace()

Database schema

Tables

-- Teams
CREATE TABLE teams (
  id TEXT PRIMARY KEY,
  org_id TEXT NOT NULL REFERENCES orgs(id),
  parent_team_id TEXT REFERENCES teams(id),
  name TEXT NOT NULL,
  slug TEXT NOT NULL,
  description TEXT,
  attach_scope_id TEXT REFERENCES scopes(id),
  created_by TEXT REFERENCES users(id),
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Team memberships
CREATE TABLE team_memberships (
  id TEXT PRIMARY KEY,
  team_id TEXT NOT NULL REFERENCES teams(id),
  user_id TEXT NOT NULL REFERENCES users(id),
  role TEXT NOT NULL DEFAULT 'member', -- admin, member, viewer
  joined_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Scope integration

Teams automatically get a scope (depth=3) for resource isolation:

INSERT INTO scopes (id, org_id, type, entity_id, parent_scope_id, depth)
VALUES ('<scope_id>', '<org_id>', 'team', '<team_id>', '<parent_scope>', 3);

Best practices

Team structure

• Keep teams focused - Each team should have a clear purpose
• Right-size membership - Too many members can dilute accountability
• Use descriptive names - Make it clear what the team does
• Assign team admins - Ensure someone can manage day-to-day operations

Team inboxes

• Route appropriately - Use routing rules to direct items to the right team
• Set escalation policies - Define what happens when items aren't handled
• Monitor queue depth - Watch for backlogs that indicate staffing issues

Last updated: 2026-01-22