docs: add offline knowledge library with project analysis and external references

- function-inventory: complete public API for 10 Rust crates + 56 Dart files - coverage-analysis: 312 Rust tests, 221 Dart tests, doc coverage gaps - doc-quality-analysis: duplications, broken refs, useless content audit - link-coverage-report: all internal/external links validated - external/teaspeak: TeaSpeak voice server architecture & protocol - external/respeak: ReSpeak org, tsclientlib, tsproto, crypto docs - external/yatqa-en/de: yat.qa admin tool (English + German) - reviews/: cross-validation reports for all analyses All documentation only, no code changes.
2026-06-13 02:00:26 +09:00
parent 89bbfa1e18
commit dd6e80f72a
13 changed files with 3358 additions and 0 deletions
@@ -0,0 +1,392 @@
+# TeaSpeak Project Knowledge Base
+
+## Overview
+
+TeaSpeak is an open-source, TeamSpeak-compatible voice communication platform hosted at `https://git.did.science/TeaSpeak`. It consists of two main repositories:
+
+- **TeaSpeak-Client** — An Electron-based desktop client (329 commits, created May 2020)
+- **TeaSpeakLibrary** — A C++ shared library providing core protocol, channel, and database functionality (208 commits, created May 2020)
+
+The project is developed by WolverinDEV / TeaSpeak and targets users who need a self-hosted, TeamSpeak-compatible voice chat solution.
+
+## Architecture
+
+### Two-Repository Design
+
+```
+TeaSpeak/
+├── TeaSpeak-Client/        # Electron desktop application
+│   ├── main.ts             # Entry point (Electron main process)
+│   ├── modules/            # TypeScript modules (core, renderer, shared, crash_handler)
+│   ├── native/             # C++ native addons (Node.js N-API)
+│   │   ├── serverconnection/   # Server connection & audio engine
+│   │   ├── codec/              # Opus codec bindings
+│   │   ├── crash_handler/      # Native crash handling
+│   │   ├── dns/                # DNS resolution
+│   │   ├── ppt/                # Protocol handling
+│   │   └── updater/            # Auto-updater
+│   ├── imports/            # Shared TypeScript definitions & vendor libs
+│   └── resources/          # Static assets
+│
+└── TeaSpeakLibrary/        # C++ static library
+    ├── CMakeLists.txt      # CMake build system
+    ├── src/
+    │   ├── protocol/       # TeamSpeak protocol implementation
+    │   ├── channel/        # Channel tree management
+    │   ├── query/          # Server query protocol
+    │   ├── sql/            # SQLite & MySQL database layer
+    │   ├── ssl/            # SSL/TLS support
+    │   ├── bbcode/         # BBCode parsing
+    │   └── misc/           # Utilities (crypto, networking, etc.)
+    └── test/               # Unit tests
+```
+
+### Client Architecture (Electron)
+
+The client uses a multi-process Electron architecture:
+
+- **Main Process** (`modules/core/main.ts`) — App lifecycle, window management, crash handling
+- **Renderer Process** (`modules/renderer/`) — UI rendering, audio controls, connection management
+- **Shared Module** (`modules/shared/`) — IPC definitions, version info, proxy utilities
+- **Native Addons** (`native/`) — C++ bindings for performance-critical operations
+
+Key TypeScript path aliases:
+- `tc-shared/*` → `imports/shared-app/*`
+- `tc-native/connection` → `native/serverconnection/exports/exports.d.ts`
+
+## Features
+
+### Voice Communication
+- Opus audio codec support (encoder/decoder)
+- Audio input/output with gain control and level metering
+- Audio mixing and interleaving
+- Voice activity detection (VAD) via libfvad
+- Audio filtering and processing pipeline
+- Sound file playback capabilities
+
+### Server Protocol
+- TeamSpeak protocol compatibility
+- Custom protocol handler with crypto support (ProtocolHandlerCrypto)
+- Packet acknowledgement and loss calculation
+- Ring buffer for reliable packet delivery
+- QuickLZ compression
+- Hardware ID (HWID) generation for client identification
+
+### Channel System
+- Tree-based channel hierarchy (TreeView)
+- Channel properties and permissions
+- BBCode formatting support
+
+### Data & Storage
+- SQLite database support
+- MySQL database support
+- Client storage and profiles
+- File transfer capabilities
+- Connection logging
+
+### Client Features
+- Auto-updater
+- Crash handler with Sentry integration
+- Window management and system tray
+- Keyboard shortcuts
+- Context menus
+- i18n (internationalization)
+- Music playback
+- URL preview
+
+## Technology Stack
+
+### Client (TeaSpeak-Client)
+| Component | Technology |
+|-----------|-----------|
+| Runtime | Electron 8.5.5 |
+| Language | TypeScript 3.9, C++ |
+| UI | HTML/CSS, jQuery, EJS templates |
+| Styling | SASS |
+| Native addons | cmake-js, Node.js N-API |
+| Build | electron-packager |
+| Error tracking | Sentry |
+
+### Library (TeaSpeakLibrary)
+| Component | Technology |
+|-----------|-----------|
+| Language | C++20 |
+| Build system | CMake 3.6+ |
+| Crypto | TomCrypt, TomMath, OpenSSL, Ed25519 |
+| Compression | QuickLZ |
+| Database | SQLite3, MySQL Connector/C++ |
+| Logging | spdlog |
+| Events | libevent |
+| Audio | Opus |
+| JSON | jsoncpp |
+| Serialization | Protocol Buffers |
+| Memory | jemalloc |
+| Crash reporting | Breakpad |
+| Terminal | CXXTerminal (server mode) |
+| Threading | Custom ThreadPool |
+| String templating | StringVariable |
+| Networking | DataPipes (includes libnice for ICE) |
+
+### External Dependencies (from libraries.txt)
+- PortAudio — Cross-platform audio I/O
+- libfvad — Voice activity detection
+- SoXR — High-quality sample rate conversion
+
+## Protocol / API
+
+### TeamSpeak Protocol Implementation
+
+The protocol layer (`TeaSpeakLibrary/src/protocol/`) implements:
+
+- **Packet** — Core packet structure and serialization
+- **CryptHandler** — Encryption/decryption for secure communication
+- **CompressionHandler** — QuickLZ-based packet compression
+- **AcknowledgeManager** — Reliable delivery with ACK tracking
+- **PacketLossCalculator** — Network quality monitoring
+- **RingBuffer** — Circular buffer for packet ordering
+- **Generation** — Protocol version/generation handling
+
+### Server Connection (Client Side)
+
+The native server connection module (`native/serverconnection/`) handles:
+
+- **ServerConnection** — Main connection state machine
+- **ProtocolHandler** — Full protocol implementation split across:
+  - `ProtocolHandlerCommands.cpp` — Command processing
+  - `ProtocolHandlerCrypto.cpp` — Crypto handshake
+  - `ProtocolHandlerPOW.cpp` — Proof of work (anti-spam)
+  - `ProtocolHandlerPackets.cpp` — Packet serialization
+- **Socket** — TCP/UDP socket management
+- **Audio subsystem** — Codec, drivers, filters, processing
+
+### Query Protocol
+
+Server query support (`src/query/`) with:
+- Command parsing (v2 and v3 formats)
+- Escape sequence handling
+
+## Build & Configuration
+
+### Building TeaSpeakLibrary
+
+```bash
+# Prerequisites: CMake 3.6+, C++20 compiler, OpenSSL, MySQL, etc.
+mkdir build && cd build
+cmake .. -DTEASPEAK_SERVER=ON
+make -j$(nproc)
+
+# Build tests (optional)
+cmake .. -DBUILD_TESTS=ON
+make -j$(nproc)
+```
+
+### Building TeaSpeak-Client
+
+```bash
+# Install dependencies
+npm install
+
+# Compile TypeScript
+npm run compile-tsc
+
+# Compile SASS
+npm run compile-sass
+
+# Generate JSON validators
+npm run compile-json-validator
+
+# Build for Linux
+npm run build-linux-64
+npm run package-linux-64
+
+# Build for Windows
+npm run build-windows-64
+npm run package-windows-64
+
+# Development mode
+npm run start-s  # Connects to localhost:8080
+```
+
+### Environment Variables
+
+- `teaclient_deploy_secret` — Deployment signing key (in `env.sh`)
+
+### Platform-Specific Dependencies
+
+- **Linux**: electron-installer-debian
+- **Windows**: electron-installer-windows, electron-winstaller, electron-wix-msi, rcedit
+
+## Key Concepts
+
+### Protocol Concepts
+- **HWID** (Hardware ID) — Unique machine identifier for client authentication
+- **POW** (Proof of Work) — Anti-spam mechanism in connection handshake
+- **Ring Buffer** — Circular buffer for managing packet ordering and retransmission
+- **Acknowledge Manager** — Tracks packet delivery confirmation
+- **Packet Loss Calculator** — Monitors network quality metrics
+
+### Audio Concepts
+- **Opus Converter** — Handles Opus encoding/decoding
+- **Audio Gain** — Volume amplification/attenuation
+- **Audio Level Meter** — Real-time audio level monitoring
+- **Audio Merger** — Combines multiple audio streams
+- **Audio Interleaved** — Audio frame interleaving for transmission
+- **Audio Event Loop** — Async audio processing pipeline
+- **VAD** (Voice Activity Detection) — Detects speech vs silence
+
+### Channel Concepts
+- **TreeView** — Hierarchical channel structure (parent/child relationships)
+- **BBCode** — Text formatting markup (TeamSpeak standard)
+- **Permission Manager** — Role-based access control
+
+### Connection Concepts
+- **ServerConnection** — Full connection lifecycle management
+- **Command Handler** — Processes server commands/responses
+- **Handshake Handler** — Initial connection negotiation
+- **Voice Connection** — Audio stream management
+- **Video Connection** — Video stream support
+- **Dummy Voice Connection** — Placeholder/mock for testing
+
+## Source Repository Structure
+
+### TeaSpeak-Client Root
+```
+.
+├── .gitignore
+├── .gitmodules
+├── bugs                        # Bug tracking
+├── build_declarations.sh       # Build script for type declarations
+├── env.sh                      # Environment variables
+├── generate-json-validators.sh # JSON schema validation generator
+├── libraries.txt               # External library references
+├── main.ts                     # Electron entry point
+├── package.json                # Node.js dependencies & scripts
+├── package-lock.json
+├── restore.sh                  # Restore script
+├── tsconfig.json               # TypeScript configuration
+├── tsconfig_render_api.json    # Renderer API TypeScript config
+├── imports/                    # Shared TypeScript types & vendor code
+│   ├── shared-app/             # Application-level shared types
+│   │   ├── audio/              # Audio type definitions
+│   │   ├── backend/            # Backend interfaces
+│   │   ├── clientservice/      # Client service definitions
+│   │   ├── connection/         # Connection type definitions
+│   │   │   └── rtc/            # WebRTC-related types
+│   │   ├── connectionlog/      # Connection logging
+│   │   ├── conversations/      # Chat/conversation types
+│   │   ├── crypto/             # Crypto interfaces
+│   │   ├── entry-points/       # Module entry points
+│   │   ├── events/             # Event definitions
+│   │   ├── file/               # File handling types
+│   │   ├── i18n/               # Internationalization
+│   │   ├── ipc/                # IPC message definitions
+│   │   ├── media/              # Media handling
+│   │   ├── music/              # Music playback
+│   │   ├── permission/         # Permission types
+│   │   ├── profiles/           # User profiles
+│   │   ├── text/               # Text processing
+│   │   ├── tree/               # Tree data structures
+│   │   ├── ui/                 # UI component types
+│   │   └── update/             # Update mechanism
+│   ├── svg-sprites/            # SVG icon sprites
+│   └── vendor/                 # Third-party libraries
+│       ├── TeaEventBus/        # Event bus implementation
+│       └── TeaClientServices/  # Client services
+├── installer/                  # Build & packaging scripts
+├── jenkins/                    # CI/CD pipeline
+├── modules/                    # TypeScript source modules
+│   ├── core/                   # Main process
+│   │   ├── app-updater/        # Auto-update logic
+│   │   ├── main-window/        # Main window management
+│   │   ├── render-backend/     # Renderer backend
+│   │   ├── ui-loader/          # UI loading
+│   │   ├── url-preview/        # URL preview
+│   │   └── windows/            # Window definitions
+│   ├── crash_handler/          # Crash handling
+│   ├── renderer/               # Renderer process
+│   │   ├── audio/              # Audio controls UI
+│   │   ├── connection/         # Connection UI
+│   │   ├── dns/                # DNS resolution
+│   │   └── hooks/              # React-like hooks
+│   ├── renderer-manifest/      # Renderer configuration
+│   └── shared/                 # Shared utilities
+│       ├── ipc/                # IPC implementation
+│       ├── process-arguments/  # CLI argument parsing
+│       ├── proxy/              # Proxy utilities
+│       └── version/            # Version management
+├── native/                     # C++ native addons
+│   ├── cmake/                  # CMake modules
+│   ├── codec/                  # Audio codec (Opus)
+│   │   └── codec/              # Codec implementation
+│   ├── crash_handler/          # Native crash handler
+│   ├── dist/                   # Distribution files
+│   ├── dns/                    # DNS resolver
+│   ├── ppt/                    # Protocol tools
+│   ├── serverconnection/       # Server connection module
+│   │   ├── exports/            # TypeScript declarations
+│   │   ├── src/
+│   │   │   ├── audio/          # Audio engine
+│   │   │   │   ├── codec/      # Opus encoder/decoder
+│   │   │   │   ├── driver/     # Audio drivers
+│   │   │   │   ├── file/       # Audio file I/O
+│   │   │   │   ├── filter/     # Audio filters
+│   │   │   │   ├── js/         # JS audio bindings
+│   │   │   │   ├── processing/ # Audio processing
+│   │   │   │   └── sounds/     # Sound effects
+│   │   │   └── connection/     # Protocol implementation
+│   │   │       ├── audio/      # Audio connection
+│   │   │       └── ft/         # File transfer
+│   │   └── test/               # Connection tests
+│   └── updater/                # Auto-updater native code
+├── resources/                  # Static resources
+└── scripts/                    # Build/utility scripts
+```
+
+### TeaSpeakLibrary Root
+```
+.
+├── CMakeLists.txt          # Build configuration
+├── main.cpp                # Test entry point
+├── src/
+│   ├── bbcode/             # BBCode parser
+│   ├── channel/            # Channel tree (TreeView)
+│   ├── converters/         # Data converters
+│   ├── lock/               # Read-write mutex
+│   ├── log/                # Logging utilities
+│   ├── misc/               # Utilities
+│   │   ├── base64.*        # Base64 encoding
+│   │   ├── digest.*        # Hash digests
+│   │   ├── hex.*           # Hex encoding
+│   │   ├── memtracker.*    # Memory tracking
+│   │   ├── net.*           # Network utilities
+│   │   └── rnd.*           # Random number generation
+│   ├── protocol/           # TeamSpeak protocol
+│   │   ├── AcknowledgeManager.*    # ACK tracking
+│   │   ├── CompressionHandler.*    # QuickLZ compression
+│   │   ├── CryptHandler.*          # Encryption
+│   │   ├── Packet.*                # Packet structure
+│   │   ├── PacketLossCalculator.*  # Loss monitoring
+│   │   ├── buffers.*               # Buffer management
+│   │   ├── generation.*            # Protocol generation
+│   │   └── ringbuffer.*            # Circular buffer
+│   ├── qlz/                # QuickLZ compression library
+│   ├── query/              # Server query protocol
+│   ├── sql/                # Database layer
+│   │   ├── sqlite/         # SQLite implementation
+│   │   └── mysql/          # MySQL implementation
+│   ├── ssl/                # SSL/TLS management
+│   ├── BasicChannel.*      # Base channel class
+│   ├── Definitions.h       # Global definitions
+│   ├── Error.*             # Error handling
+│   ├── EventLoop.*         # Event loop
+│   ├── License.*           # License management
+│   ├── PermissionManager.* # Permission system
+│   ├── Properties.*        # Property system
+│   └── Variable.*          # Variable system
+└── test/                   # Unit tests
+    ├── RingTest.cpp
+    ├── CommandTest.cpp
+    ├── ChannelTest.cpp
+    ├── PermissionTest.cpp
+    └── ...
+```