Summary

Document the Facade v2.0 API layer that provides simplified, high-level interfaces for each network protocol (TCP, UDP, HTTP, WebSocket, QUIC).

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (kcenon/common_system#325)

Background (Why)

network_system provides 5 facade classes at include/kcenon/network/facade/ that offer simplified APIs for each protocol. While the low-level protocol implementations are partially documented, the facade layer—which is the primary user-facing API—is not documented.

Source files:

• include/kcenon/network/facade/tcp_facade.h — Simplified TCP client/server
• include/kcenon/network/facade/udp_facade.h — Simplified UDP messaging
• include/kcenon/network/facade/http_facade.h — Simplified HTTP client/server
• include/kcenon/network/facade/websocket_facade.h — Simplified WebSocket connections
• include/kcenon/network/facade/quic_facade.h — Simplified QUIC connections

Scope (What)

Create docs/FACADE_GUIDE.md covering:

1. Facade Pattern Overview

• Why facades exist (simplify complex protocol internals)
• Relationship to underlying protocol implementations
• When to use facade vs direct protocol API

2. TCP Facade (tcp_facade.h)

• Client API: connect, send, receive, disconnect
• Server API: listen, accept, broadcast
• Configuration: timeouts, buffer sizes, keep-alive
• Example: Echo server in <20 lines

3. UDP Facade (udp_facade.h)

• Datagram send/receive API
• Multicast support
• Broadcast support
• Example: Simple discovery protocol

4. HTTP Facade (http_facade.h)

• Client API: GET, POST, PUT, DELETE
• Server API: route registration, middleware
• Request/response types
• Example: REST API server

5. WebSocket Facade (websocket_facade.h)

• Client API: connect, send, receive, close
• Server API: upgrade, broadcast
• Message types (text, binary, ping/pong)
• Example: Chat application

6. QUIC Facade (quic_facade.h)

• Connection API with 0-RTT support
• Stream multiplexing
• Migration support
• Example: Multi-stream data transfer

7. Common Patterns Across Facades

• Error handling (Result pattern)
• Async operations
• TLS configuration
• Logging integration

8. Migration from Low-Level API

• When to switch from facade to direct API
• How facades map to internal types

Acceptance Criteria

• All 5 facade classes documented with full API
• Usage examples for each facade (server + client)
• Common patterns section
• Configuration options per facade
• Migration guidance from low-level API
• At least 5 complete code examples