Team Management Overview
Understand how team management works in CodeCourier, including project hierarchy, member roles, collaboration features, and access control.
CodeCourier is built for team collaboration. Every feature in the platform - sandboxes, workflows, personas, issue sessions, and learnings - is scoped to a project, and projects support multiple members with distinct roles. This section explains how the team management system works and how to use it effectively.
Project-Centric Architecture
The fundamental organizational unit in CodeCourier is the project. A project represents a codebase, product, or initiative that your team is working on. All resources - sandboxes, runs, workflows, personas, issue sessions, learnings, issues, and API keys - belong to a project.
Every project has:
- Name and slug - A human-readable name and URL-friendly identifier
- Owner - The user who created the project (has full control)
- Members - Other users with access to the project
- Settings - Configuration for system prompts, API keys, environment variables, and more
- Optional GitHub repository - A linked repository for code deployment and PR management
- Optional logo - A custom project logo uploaded to storage
Users can be members of multiple projects simultaneously. The platform tracks the user's last active project and switches context automatically when they navigate between projects.
User and Organization Model
CodeCourier uses Clerk for authentication. When a user signs up or logs in, a corresponding user record is created in the Convex database with their Clerk ID, email, name, and profile image. The user record is the identity anchor for all project memberships, API keys, and activity tracking.
The team model is flat by design - there are no nested organizations or team hierarchies. Each project has a direct list of members, and each member has a role that determines their permissions. This simplicity keeps access control straightforward and predictable.
Multi-Project Users
Member Lifecycle
The lifecycle of a project member follows these stages:
- Invitation- An owner or admin invites a user by email address. The membership is created with status "pending".
- Acceptance- The invited user sees the pending invitation in their dashboard and accepts it. The status changes to "accepted" and they gain access to the project.
- Active membership - The member can access all project resources according to their role (owner, admin, or member).
- Role changes - Owners can change member roles. Admins can be promoted to owners or demoted to members.
- Removal - Owners and admins can remove members. The membership record is deleted permanently.
Users can also decline a pending invitation, which deletes the membership record without the user ever gaining access to the project.
Collaboration Features
When multiple team members work on the same project, they benefit from several collaboration features:
Shared Resources
All project resources are shared among members. Sandboxes, runs, workflows, personas, and issue sessions created by any member are visible to all members. This transparency ensures everyone can see the project's activity and status.
Real-Time Updates
CodeCourier uses Convex's reactive data model, which means all project data updates in real-time across all connected clients. When one team member starts a workflow run, another member sees the run appear immediately without refreshing. This extends to all entities: sandboxes, runs, issue sessions, and learnings.
Notification System
The project notification system alerts team members about important events: run completions, run failures, PR creation, PR merges, member joins, and workflow completions. Notifications appear in the inbox and track read/unread status per user.
Activity Counters
The project maintains denormalized counters that provide quick visibility into project activity: total sandboxes, active sandboxes, total runs, completed runs, failed runs, total workflows, total members, and pending invitations. These counters update in real-time as the project's state changes.
Access Control Model
CodeCourier uses a role-based access control (RBAC) model with three roles: Owner, Admin, and Member. Every API endpoint that accesses project data first verifies that the requesting user is an active member of the project. Some operations additionally require admin or owner privileges.
The access control is enforced at the Convex function level using shared authentication helpers (getProjectForMember, requireProjectAdmin, requireProjectOwner). These functions check the user's membership and role before allowing the operation to proceed.
Pending Members
isMemberOfProject internal query explicitly rejects pending memberships. A user must accept the invitation before they can see or interact with any project data.