OpenSpeak/openspec/specs/003-channel-management.md

# Feature Specification: Channel Management

**ID:** CHANNEL-001
**Version:** 1.0
**Status:** Planned
**Priority:** Critical

## Overview
Channel management system for creating, updating, deleting, and organizing voice communication spaces.

## Channel Model

### Channel Entity
```protobuf
message Channel {
  string id = 1;                    // Unique identifier (UUID)
  string name = 2;                  // Display name
  string description = 3;           // Optional description
  bool is_public = 4;              // Public or private
  string owner_id = 5;             // User who created the channel
  repeated string member_ids = 6;  // List of member IDs
  int32 max_users = 7;             // Max concurrent users (0 = unlimited)
  int64 created_at = 8;            // Unix timestamp
  int64 updated_at = 9;            // Unix timestamp
  ChannelStatus status = 10;       // Active, archived, deleted
}

enum ChannelStatus {
  ACTIVE = 0;
  ARCHIVED = 1;
  DELETED = 2;
}
```

### Channel Properties
- **ID:** UUID v4, immutable
- **Name:** 1-50 characters, alphanumeric + spaces/hyphens
- **Description:** Optional, max 500 characters
- **Public:** Anyone can join (requires authentication only)
- **Private:** Admin only, membership by invitation
- **Max Users:** Unlimited by default, configurable per channel
- **Status:** Active by default, can be archived (soft-delete) or deleted (hard-delete)

## Channel Lifecycle

### Creation
**Requirements:**
- User must be authenticated
- User must have `channels:create` permission
- Name must be unique (case-insensitive)
- At least 2 characters, max 50

**Process:**
```
Client requests CreateChannel
    ↓
Server validates permissions
    ↓
Server validates name uniqueness and format
    ↓
Server creates channel with unique ID
    ↓
Server marks creator as owner
    ↓
Server broadcasts ChannelCreated event
    ↓
Return channel object to client
```

### Joining
**Requirements:**
- User must be authenticated
- Channel must exist and be active
- For public channels: user must be authenticated
- For private channels: user must be invited or owner

**Process:**
```
Client requests JoinChannel(channel_id)
    ↓
Server validates channel exists
    ↓
Server validates access permissions
    ↓
Check max_users capacity
    ↓
Add user to channel members list
    ↓
Broadcast UserJoined event to channel
    ↓
Return success and list of current members
```

### Leaving
**Requirements:**
- User must be in channel

**Process:**
```
User requests LeaveChannel or disconnects
    ↓
Server removes user from channel members
    ↓
Broadcast UserLeft event to channel
    ↓
Clean up user's audio streams
    ↓
Confirm departure
```

### Updates
**Allowed Updates:**
- Name (must remain unique)
- Description
- Public/Private status
- Max users capacity
- Owner reassignment

**Requirements:**
- Only channel owner or admin can update
- Name must remain unique
- Validation of new values

### Deletion
**Soft Delete (Archive):**
- Channel marked as archived
- Existing members can still access
- New users cannot join
- Data preserved for recovery
- Used for channels that may return

**Hard Delete:**
- Permanently removed from system
- All associated data deleted
- Cannot be recovered
- Used for spam/abuse

## Presence & Status

### User Presence
**User State in Channel:**
```
Connected: User is in channel voice call
Inactive: User is in channel but no audio activity (15+ seconds)
Typing: User has text input focus (future)
Away: User idle for >5 minutes (future)
```

### Channel Activity Feed (Future)
- User joined
- User left
- User muted/unmuted
- Channel created/updated
- Admin actions

## Permissions Model

### Channel Owner
- Can modify channel settings
- Can kick members
- Can delete channel
- Can transfer ownership
- Can make channel private/public

### Channel Member
- Can join/leave
- Can speak in channel
- Can see member list
- Can see channel info

### Server Admin
- Can manage all channels
- Can override any permission
- Can archive/delete channels
- Can view audit logs

## API Endpoints (gRPC)

### Channel Service
```protobuf
service ChannelService {
  rpc CreateChannel(CreateChannelRequest) returns (CreateChannelResponse);
  rpc GetChannel(GetChannelRequest) returns (Channel);
  rpc ListChannels(ListChannelsRequest) returns (ListChannelsResponse);
  rpc UpdateChannel(UpdateChannelRequest) returns (Channel);
  rpc DeleteChannel(DeleteChannelRequest) returns (DeleteChannelResponse);
  rpc JoinChannel(JoinChannelRequest) returns (JoinChannelResponse);
  rpc LeaveChannel(LeaveChannelRequest) returns (LeaveChannelResponse);
  rpc ListMembers(ListMembersRequest) returns (ListMembersResponse);
  rpc KickMember(KickMemberRequest) returns (KickMemberResponse);
}
```

## Data Persistence (Phase 2)
Initially, channels are in-memory and lost on server restart.

**Future:** Persistent storage
- Channel metadata in database
- Member lists persisted
- Activity logs
- Backup/restore capability

## Configuration
- Max channels allowed on server
- Max members per channel (default)
- Channel name validation rules
- Soft delete retention period (before hard delete)
- Archive auto-cleanup policy

## Error Handling
- Duplicate channel name: Return AlreadyExists error
- Channel not found: Return NotFound error
- Access denied: Return PermissionDenied error
- Channel full: Return ResourceExhausted error
- User already in channel: Return AlreadyExists error

## Notifications

**Events Broadcast to Channel:**
- UserJoined(user_id, timestamp)
- UserLeft(user_id, timestamp)
- ChannelUpdated(channel, updater_id)
- ChannelDeleted(channel_id, timestamp)

## Testing Strategy
- Unit tests for channel creation with various inputs
- Unit tests for permission validation
- Integration tests for join/leave operations
- Concurrency tests for multiple users joining simultaneously
- Tests for max capacity enforcement
- Soft delete and restore functionality tests
- Event broadcast verification