# Project Context

## Purpose
OpenSpeak is an open-source TeamSpeak alternative built in Go. The project provides both server and client applications to enable voice communication over networks. The goal is to create a free, self-hosted, feature-rich voice communication platform.

## Tech Stack
- **Language:** Go (golang)
- **Protocol:** Protocol Buffers/gRPC for client-server communication
- **Architecture:** Modular client-server architecture

## Project Conventions

### Code Style
- Follow standard Go conventions using `gofmt` for formatting
- Use `go lint` and `go vet` for code quality checks
- PascalCase for exported identifiers, camelCase for unexported
- Descriptive variable names that indicate purpose
- Keep lines under 120 characters where practical
- Comment all exported functions and types

### Architecture Patterns
- **Client-Server Model:** Separate executable applications for server and client with clear responsibilities
- **Protocol Buffers/gRPC:** Use protobuf for message definition and gRPC for efficient service communication
- **Modular by Feature:** Organize packages around domain concepts (e.g., `voice`, `auth`, `streaming`, `config`)
- **Repository Pattern:** Abstract data access logic where applicable
- **Middleware Pattern:** Use middleware for cross-cutting concerns like logging, authentication, and error handling

### Testing Strategy
- **Unit Tests:** Use Go's standard `testing` package (`testing.T`)
- **Table-Driven Tests:** Use data-driven test patterns for comprehensive test coverage
- **Integration Tests:** Test components working together, especially client-server communication
- **Benchmarks:** Use `testing.B` for performance-critical code paths
- Test files should be in the same package as the code being tested with `_test.go` suffix
- Aim for meaningful test coverage of business logic

### Git Workflow
- **Branching Strategy:** Feature branches for development
  - `feature/*` for new features
  - `bugfix/*` for bug fixes
  - `main` for stable releases
- **Commit Conventions:** Conventional commits
  - `feat:` for new features
  - `fix:` for bug fixes
  - `docs:` for documentation changes
  - `refactor:` for code refactoring
  - `test:` for test additions/changes
  - `perf:` for performance improvements
  - Example: `feat: add voice channel broadcasting to server`

## Domain Context

### Voice Communication Architecture
- **Audio Codec:** Opus (provides best latency/quality trade-off)
  - Used by Discord, Telegram, and WebRTC
  - Supports variable bitrate for bandwidth efficiency
  - Native Go support via external libraries
- **Voice Stream Model:** Server broadcast to channel members
  - Clients send encoded audio packets to server
  - Server receives from all speakers and broadcasts to channel members
  - Server handles basic audio packet routing (not mixing/processing)
  - Each user receives individual streams from other speakers

### Server Responsibilities
- **Authentication & Authorization:** User login, token validation (admin tokens stored locally initially)
- **Channel Management:** Create, delete, manage voice channels
- **Voice Stream Routing:** Receive audio packets from clients, broadcast to channel members
- **User Presence Tracking:** Track online status and which channels users are in
- **Connection Management:** Handle client connections/disconnections and cleanup

### Client Responsibilities (Desktop GUI)
- **Audio Capture:** Record audio from user's microphone
- **Audio Encoding:** Encode to Opus format before sending to server
- **Audio Playback:** Decode received streams and mix for playback to speakers
- **UI Management:** Display channels, users, connection status
- **Stream Handling:** Handle multiple concurrent incoming audio streams

### Core Features (Initial Release)
- Voice channels (persistent, users can join/leave)
- Authentication (admin token-based access)
- Real-time voice communication in channels
- User presence tracking (who's online, who's in which channel)

## Important Constraints
- **Audio Latency:** Must minimize latency for real-time voice communication (target <100ms round-trip)
- **Concurrency:** Server must handle multiple concurrent connections and voice streams efficiently
- **Network Bandwidth:** Optimize audio bitrate vs. quality (Opus helps with this)
- **Memory Management:** Goroutines and channels for concurrent audio packet handling
- **Platform Support:** Go backend (cross-platform server), GUI client (consider platform specifics)
- **Open Source:** Ensure all dependencies are compatible with chosen license (consider GPL/MIT/Apache)

## External Dependencies

### Core Libraries (To Be Determined)
- **Audio Codec:** `github.com/gopxl/beep` or `pion/webrtc` for Opus support
- **gRPC/Protobuf:** `google.golang.org/grpc` and `google.golang.org/protobuf` (already chosen)
- **GUI Framework:** (TBD - consider Fyne, Gio, or Ebiten for cross-platform desktop)
- **Logging:** Standard library or `github.com/sirupsen/logrus` for structured logging

### Server Infrastructure
- **Network:** Raw TCP/UDP connections, gRPC for control plane
- **Concurrency:** Go goroutines and channels for audio packet handling
- **Configuration:** Local config files for server settings, admin token storage
- **Data Persistence:** Not needed for MVP (stateless server, optional later for user/channel persistence)