📚 Detailed documentation for major subsystems

This page provides detailed information about the major subsystems in ascii-chat. Each topic covers architecture, implementation details, usage patterns, and best practices. The categories below correspond to the CMake library modules used to build ascii-chat.

🛠️ Utilities

🛠️ Core utility functions for string manipulation, paths, IP parsing, and formatting

Utility Functions - String, path, IP, UTF-8, CRC32, formatting utilities
systemd integration - Linux service units, notifications, and installation

📦 Data Structures

📦 High-performance data structures for memory and packet management

Owned Buffers - Bounded aligned storage with explicit ownership
Ring Buffer - Lock-free circular buffers for audio/video
Packet Queue - Thread-safe per-client packet queues
uthash library "Hash Table" - High-performance client ID lookup

🔌 Platform Abstraction

🔌 Cross-platform abstraction for threading, sockets, and system APIs

Platform Abstraction Layer README - Comprehensive guide covering cross-platform threading, mutexes, sockets, terminal I/O, crash handling, static initialization, and OS portability (Windows/Linux/macOS)
Webcam Capture - Cross-platform webcam capture functionality

🔐 Cryptography

🔐 End-to-end encryption and secure communication

Cryptography - Encryption architecture and security details
Authenticated packet records and rotation - Packet authentication, replay protection, and key rotation
Handshake Protocol - Secure connection establishment
Keys Module - SSH/GPG key parsing and validation

📹 Video to ASCII Conversion

📹 Video capture, ASCII conversion, and frame layout

Video to ASCII Conversion - The root video category containing all video code and modules.
Video Frame Management - RGB frame structures and lifecycle
Grid Layout System - Multi-frame layout for multi-user video
Palette Management - ASCII character palettes with UTF-8 support

🔊 Audio Processing

🔊 Audio capture, playback, and multi-client mixing

Audio System - Audio capture and playback with PortAudio
Audio Mixer - Multi-client audio mixing with ducking

⚙️ Core Infrastructure

⚙️ Core functionality including error handling, logging, and configuration

main() - Unified binary dispatcher routing to server or client mode
Common Definitions - Core utilities, macros, memory debugging, constants
Error Handling System - Typed error codes, error context, thread-safe errors
Logging System - Level-based logging, rate limiting, file output
Options and Configuration - Command-line parsing and TOML config
Configuration - TOML configuration file management

🖥️ User Interface

Terminal presentation, input routing, widgets, and interactive screens.

UI Architecture - Snapshot-driven terminal presentation and input routing
Terminal UI (TUI) - Interactive screens, resizing, diagnostics, and testing
Keyboard Shortcuts - Current global, media, prompt, and modal bindings

🌐 Network

🌐 Network I/O, packet protocol, and audio/video streaming

Network I/O - Socket operations, timeouts, connections, packet protocol
HTTP Basic authentication - Bounded credential parsing and comparison
QUIC and WebTransport - Native QUIC, HTTP/3, datagrams, trust, and migration
Network Compression - zstd compression utilities for network payload optimization
Packet Types - Network packet structures and definitions
Audio/Video Networking - Network APIs for audio/video streaming

💻 Client Application

💻 Client application for connecting to servers and streaming media

Overview of Client - Complete client architecture overview
Client Main Entry Point - Main lifecycle orchestration and reconnection logic
Connection Management - Server connection, packet transmission, and state tracking
Protocol Handler - Packet reception and processing
Media Capture - Webcam video capture and transmission
Terminal Display - Terminal rendering and TTY management
Audio Processing - Audio capture, playback, and jitter buffering
Connection Keepalive - Ping/pong and timeout detection
Cryptographic Operations - Handshake and key management

🖥️ Server

🖥️ ascii-chat server implementation and architecture

Overview of Server - Multi-client server with per-client threading, encryption, and real-time rendering
Server Main Entry Point - Server initialization, signal handling, and connection management
Client Management - Per-client lifecycle management and threading coordination
Protocol Handler - Network packet processing and protocol implementation
Stream Generation - Multi-client video mixing and ASCII frame generation
Render Threads - Per-client rendering threads with rate limiting
Statistics and Monitoring - Performance monitoring and resource utilization tracking
Cryptographic Operations - Per-client cryptographic handshake and session encryption management

🔍 Discovery Service (ACDS)

🔍 ascii-chat Discovery Service for session management and NAT traversal

ACDS Overview - Complete discovery service architecture and protocol
ACDS Server - TCP server, packet dispatch, and client handlers
Session Database - SQLite-based session storage and management
WebRTC Signaling - SDP/ICE relay for P2P connections
Identity Management - Ed25519 identity keys for ACDS
Session Strings - Human-friendly session identifiers

🔧 Development & Debugging

🔧 Build system, testing infrastructure, and debugging utilities

Dependencies - Third-party libraries and build requirements
Build System - CMake configuration, cross-platform compilation, build types
Testing - Test framework, test runner, Docker testing, coverage reporting
Debugging Utilities - Error tracking, memory leak detection, diagnostics
Error Handling System - Typed error codes, error context, thread-safe errors
Exit Codes - Exit code categories and error descriptions from asciichat_error_t
Lock Debugging - Lock tracking, deadlock detection, contention analysis

🧰 Tooling

🧰 Source-to-source transformation tools for debugging and code quality.

Defer Tool - 🔄 Go/Zig-style defer statements for automatic cleanup
Panic Instrumentation - 🚨 Per-statement logging for crash debugging

Authored Documentation

Focused documentation that supplements the source-level topics is organized below by purpose. These links intentionally live in Topic Categories rather than in a flat Pages sidebar.