# Feature Specification: Server Core Architecture

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

## Overview
Server application providing voice communication service, handling client connections, channel management, user presence, and voice packet routing.

## Architecture

### Overall Server Architecture
```
┌─────────────────────────────────────────────────────┐
│                    OpenSpeak Server                  │
├─────────────────────────────────────────────────────┤
│  gRPC Server (Port 50051)                           │
│  ┌──────────────────────────────────────────────┐  │
│  │ Authentication Interceptor                    │  │
│  └────────────────────────────────────────────┬─┘  │
│                                                 │    │
│  ┌─────────────────┬─────────────┬─────────────┴─┐ │
│  ▼                 ▼              ▼                ▼ │
│ Auth Service  Channel Service Presence Service Voice │
│              Manager            Manager       Service │
│                                                      │
│  ┌──────────────────────────────────────────────┐  │
│  │ State Management Layer                        │  │
│  │ • Users & Sessions                           │  │
│  │ • Channels & Members                         │  │
│  │ • Presence Data                              │  │
│  │ • Voice Streams                              │  │
│  └──────────────────────────────────────────────┘  │
│                                                      │
│  ┌──────────────────────────────────────────────┐  │
│  │ Supporting Infrastructure                     │  │
│  │ • Logging                                    │  │
│  │ • Configuration Management                   │  │
│  │ • Error Handling                             │  │
│  │ • Metrics/Monitoring                         │  │
│  └──────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
```

### Package Structure
```
openspeak/
├── cmd/
│   └── openspeak-server/
│       └── main.go
├── internal/
│   ├── auth/
│   │   ├── token_manager.go
│   │   ├── permission_checker.go
│   │   └── auth_test.go
│   ├── channel/
│   │   ├── manager.go
│   │   ├── channel.go
│   │   ├── store.go
│   │   └── channel_test.go
│   ├── presence/
│   │   ├── manager.go
│   │   ├── session.go
│   │   ├── event_broadcaster.go
│   │   └── presence_test.go
│   ├── voice/
│   │   ├── router.go
│   │   ├── stream.go
│   │   ├── packet.go
│   │   └── voice_test.go
│   ├── config/
│   │   └── config.go
│   ├── logger/
│   │   └── logger.go
│   └── grpc/
│       ├── server.go
│       ├── auth_interceptor.go
│       └── handlers/
│           ├── auth_handler.go
│           ├── channel_handler.go
│           ├── presence_handler.go
│           └── voice_handler.go
├── proto/
│   ├── auth.proto
│   ├── channel.proto
│   ├── presence.proto
│   ├── voice.proto
│   └── common.proto
├── config/
│   └── config.yaml
└── go.mod
```

## Server Components

### 1. Authentication Manager
**File:** `internal/auth/token_manager.go`

**Responsibilities:**
- Load admin tokens from configuration
- Validate tokens on each request
- Check token expiration
- Manage token rotation (future)
- Audit authentication attempts

**Interface:**
```go
type TokenManager interface {
  ValidateToken(ctx context.Context, token string) (*TokenInfo, error)
  RevokeToken(token string) error
  ListTokens() []*TokenInfo
}
```

### 2. Channel Manager
**File:** `internal/channel/manager.go`

**Responsibilities:**
- Create/delete channels
- Manage channel state
- Enforce permission rules
- Broadcast channel events
- Track channel members
- Clean up empty channels

**Data Structure:**
```go
type Manager struct {
  channels map[string]*Channel
  mu       sync.RWMutex
  events   chan ChannelEvent
}
```

### 3. Presence Manager
**File:** `internal/presence/manager.go`

**Responsibilities:**
- Track user sessions
- Manage presence status
- Detect idle users
- Handle disconnections
- Broadcast presence events
- Maintain online user list

**Key Methods:**
```go
type Manager interface {
  CreateSession(userID string) *Session
  EndSession(userID string) error
  UpdatePresence(userID string, status Status) error
  GetOnlineUsers() []*UserPresence
  GetChannelMembers(channelID string) []*UserPresence
}
```

### 4. Voice Router
**File:** `internal/voice/router.go`

**Responsibilities:**
- Receive voice packets from clients
- Route to appropriate channel
- Broadcast to channel members
- Handle packet buffering
- Drop outdated packets
- Monitor stream quality

**Packet Flow:**
```go
type VoiceRouter interface {
  PublishVoicePacket(clientID, channelID string, packet *VoicePacket) error
  SubscribeToChannel(clientID, channelID string) (<-chan *VoicePacket, error)
  UnsubscribeFromChannel(clientID, channelID string) error
}
```

### 5. gRPC Server
**File:** `internal/grpc/server.go`

**Responsibilities:**
- Manage gRPC server lifecycle
- Register service implementations
- Handle client connections
- Apply authentication interceptor
- Handle connection timeouts

**Port:** 50051 (configurable)
**TLS:** Required for production (configurable for dev)

### 6. Configuration Manager
**File:** `internal/config/config.go`

**Loads from:**
- Environment variables (takes precedence)
- `config/config.yaml`
- Command-line flags
- Defaults in code

**Configuration Items:**
```go
type Config struct {
  Server struct {
    Host           string
    Port           int
    TLSCert        string
    TLSKey         string
  }
  Auth struct {
    TokensFile     string
    TokenTTL       time.Duration
  }
  Audio struct {
    DefaultBitrate int
    JitterBuffer   int
  }
  Logging struct {
    Level          string
    OutputFormat   string
  }
}
```

### 7. Logging System
**File:** `internal/logger/logger.go`

**Features:**
- Structured logging
- Configurable log level (debug, info, warn, error)
- File and stdout output
- Request ID correlation
- Performance metrics logging

**Usage:**
```go
logger.Info("User connected", "user_id", userID, "channel_id", channelID)
logger.Error("Voice routing failed", "error", err, "packet_id", packetID)
```

## Concurrency Model

### Goroutine Strategy
- **Per-Connection Handler:** One goroutine per client connection
  - Handles incoming RPC requests
  - Listens for outgoing events
  - Cleanup on disconnect

- **Voice Broadcasting:** One goroutine per channel (future optimization)
  - Aggregates voice packets
  - Broadcasts to subscribers

- **Presence Tracker:** Background goroutine
  - Checks for idle users every 30 seconds
  - Detects stale connections
  - Updates presence status

### Channel-Based Communication
- Unbuffered channels for request/response
- Buffered channels for event broadcasting
- Select statements for event handling

### Locks & Synchronization
```go
// Read-heavy, so use RWMutex for channel/user maps
channels map[string]*Channel
mu       sync.RWMutex

// Voice packets: channel-based, no explicit locks
voiceChannels map[string]chan *VoicePacket
```

## Error Handling

### Server-Level Errors
```go
const (
  ErrUnauthorized      = "unauthorized"
  ErrInvalidRequest    = "invalid_request"
  ErrChannelNotFound   = "channel_not_found"
  ErrChannelFull       = "channel_full"
  ErrUserNotFound      = "user_not_found"
  ErrInternalError     = "internal_error"
)
```

### Error Propagation
- Validation errors: Return immediately to client
- Internal errors: Log details, return generic message to client
- Voice errors: Log, skip packet, continue
- Connection errors: Graceful cleanup, retry for client

## Metrics & Monitoring

### Server Metrics (Future)
- Connected users count
- Active channels count
- Voice packets per second
- Average latency
- Memory usage
- CPU usage

### Logging Points
- User connection/disconnection
- Channel creation/deletion
- Authentication failures
- Voice packet routing errors
- Presence status changes
- Server startup/shutdown

## Shutdown Procedure
```
Receive shutdown signal
    ↓
Set graceful shutdown mode
    ↓
Stop accepting new connections
    ↓
Wait up to 30 seconds for active connections to close
    ↓
Force close remaining connections
    ↓
Cleanup resources
    ↓
Exit
```

## Scalability Considerations (Future)
- Horizontal scaling: Multiple server instances with load balancer
- Message queue for voice packets (Redis/RabbitMQ)
- Distributed session storage (Redis)
- Database for persistent data
- Voice stream optimization (SFU pattern, not broadcast)

## Configuration Example

```yaml
server:
  host: 0.0.0.0
  port: 50051
  tls_cert: ""  # Empty = no TLS for development
  tls_key: ""

auth:
  tokens_file: /etc/openspeak/admin_tokens.json
  token_ttl: 0  # 0 = no expiration

audio:
  default_bitrate: 64
  jitter_buffer_ms: 50

logging:
  level: info
  output_format: json
  output_file: /var/log/openspeak/server.log

voice:
  max_broadcast_lag_ms: 100
  max_packet_age_ms: 500
```

## Testing Strategy
- Unit tests for each manager component
- Integration tests for gRPC handlers
- Concurrency tests with multiple clients
- Voice packet loss simulation tests
- Connection timeout and cleanup tests
- Performance benchmarks for voice routing
- Load tests with high concurrency
