Add organization/team management #61
Description
User Story
As an organization administrator, I want to manage teams and members so that I can organize access and collaboration across the organization.
Design
Command Interface
# Organization commands
qctl org show
qctl org settings
qctl org usage
# Team management
qctl team list
qctl team create platform-eng --description "Platform Engineering"
qctl team show platform-eng
qctl team delete platform-eng
# Member management
qctl team member list platform-eng
qctl team member add platform-eng james.maes@acme.com
qctl team member remove platform-eng james.maes@acme.com
qctl team member invite platform-eng alice@external.com --role developer
# App ownership
qctl team app assign platform-eng orders-api
qctl team app unassign platform-eng orders-api
qctl team app list platform-engOrganization Hierarchy
┌─────────────────────────────────────────────────────────────────┐
│ Organization Structure │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Organization: ACME Corp │
│ ├── Owners (1) │
│ │ └── cto@acme.com │
│ │ │
│ ├── Teams │
│ │ ├── Platform Engineering │
│ │ │ ├── Members: james.maes, alice.smith, bob.jones │
│ │ │ └── Apps: orders-api, inventory-api, gateway │
│ │ │ │
│ │ ├── Frontend Team │
│ │ │ ├── Members: carol.white, dan.brown │
│ │ │ └── Apps: web-app, mobile-bff │
│ │ │ │
│ │ └── Data Team │
│ │ ├── Members: eve.green │
│ │ └── Apps: etl-pipeline, analytics-api │
│ │ │
│ └── Service Accounts │
│ ├── ci-pipeline (CI/CD) │
│ └── monitoring (Observability) │
│ │
└─────────────────────────────────────────────────────────────────┘
Output Format
$ qctl org show
Organization: ACME Corp
ID: org_abc123
Plan: Enterprise
Created: 2025-06-15
Usage:
Teams: 3 / unlimited
Members: 8 / unlimited
Apps: 7 / unlimited
Deployments (month): 156 / unlimited
Owners:
cto@acme.com
$ qctl team list
NAME MEMBERS APPS DESCRIPTION
platform-eng 3 3 Platform Engineering
frontend 2 2 Frontend Development
data 1 2 Data & Analytics
$ qctl team show platform-eng
Team: Platform Engineering
ID: team_xyz789
Created: 2025-07-01
Created by: james.maes@acme.com
Members (3):
NAME EMAIL ROLE JOINED
James Maes james.maes@acme.com admin 2025-07-01
Alice Smith alice.smith@acme.com developer 2025-07-15
Bob Jones bob.jones@acme.com developer 2025-08-01
Apps (3):
NAME ENVIRONMENTS
orders-api dev, staging, prod
inventory-api dev, staging, prod
gateway dev, staging, prod
$ qctl team member invite platform-eng alice@external.com --role developer
Invitation sent to alice@external.com
Role: developer
Expires: 2026-01-10 (7 days)
Pending invitations:
alice@external.com - developer - expires 2026-01-10
Invitation Flow
┌──────────────────────────────────────────────────────────────┐
│ Member Invitation Flow │
├──────────────────────────────────────────────────────────────┤
│ │
│ 1. Admin invites user │
│ qctl team member invite team alice@external.com │
│ │ │
│ ▼ │
│ 2. Voyage sends invitation email │
│ [Accept Invitation] button with unique token │
│ │ │
│ ▼ │
│ 3. User clicks link, creates account or links SSO │
│ │ │
│ ▼ │
│ 4. User added to team with specified role │
│ Audit event recorded │
│ │
└──────────────────────────────────────────────────────────────┘
API Integration
GET /v1/org
GET /v1/org/usage
PUT /v1/org/settings
GET /v1/teams
POST /v1/teams
GET /v1/teams/{teamId}
DELETE /v1/teams/{teamId}
GET /v1/teams/{teamId}/members
POST /v1/teams/{teamId}/members
DELETE /v1/teams/{teamId}/members/{userId}
POST /v1/teams/{teamId}/invitations
GET /v1/teams/{teamId}/apps
POST /v1/teams/{teamId}/apps
DELETE /v1/teams/{teamId}/apps/{appId}
Files to Create/Modify
| File | Action | Description |
|---|---|---|
qctl-core/src/main/java/io/qrun/qctl/core/org/OrgCommand.java |
Create | Organization commands |
qctl-core/src/main/java/io/qrun/qctl/core/org/ShowCommand.java |
Create | Show org details |
qctl-core/src/main/java/io/qrun/qctl/core/org/UsageCommand.java |
Create | Show org usage |
qctl-core/src/main/java/io/qrun/qctl/core/team/TeamCommand.java |
Create | Team command group |
qctl-core/src/main/java/io/qrun/qctl/core/team/ListCommand.java |
Create | List teams |
qctl-core/src/main/java/io/qrun/qctl/core/team/CreateCommand.java |
Create | Create team |
qctl-core/src/main/java/io/qrun/qctl/core/team/ShowCommand.java |
Create | Show team details |
qctl-core/src/main/java/io/qrun/qctl/core/team/MemberCommand.java |
Create | Member management |
qctl-core/src/main/java/io/qrun/qctl/core/team/AppCommand.java |
Create | App assignment |
qctl-core/src/main/java/io/qrun/qctl/core/team/InviteCommand.java |
Create | Member invitation |
qctl-core/src/main/java/io/qrun/qctl/core/model/Organization.java |
Create | Organization model |
qctl-core/src/main/java/io/qrun/qctl/core/model/Team.java |
Create | Team model |
qctl-core/src/main/java/io/qrun/qctl/core/model/Member.java |
Create | Member model |
qctl-core/src/main/java/io/qrun/qctl/core/model/Invitation.java |
Create | Invitation model |
Implementation Tasks
- Create OrgCommand with show/settings/usage subcommands
- Create TeamCommand group
- Implement team CRUD operations
- Implement member list/add/remove
- Add member invitation with email
- Implement app assignment to teams
- Add team usage statistics
- Show pending invitations
- Add invitation expiry handling
- Implement team deletion with safety checks
- Add confirmation prompts for destructive operations
- Write unit tests for team operations
Acceptance Criteria
- Can view organization details and usage
- Can create and delete teams
- Can add and remove team members
- Can invite external users via email
- Can assign apps to teams
- Team members inherit team-scoped permissions
- Deleting a team requires confirmation
- Pending invitations are visible
- Usage metrics show current vs limits