# Documentation Index — WebSocket Relay

> **Purpose:** This file serves as the primary knowledge base entry point for AI assistants working with this codebase. Read this file first to understand where to find detailed information.

## How to Use This Documentation

1. **Start here** — this index contains summaries of every documentation file
2. **Check the summary tables** below to determine which file has the information you need
3. **Only load additional files** when you need deeper detail on a specific topic
4. **Cross-references** are provided to help navigate between related topics

---

## Project Quick Reference

| Fact | Value |
|------|-------|
| **Project** | WebSocket Relay Server |
| **Language** | Go 1.21 |
| **Purpose** | Broadcast WebSocket messages to all connected clients (P2P relay) |
| **Entry Point** | `main.go` |
| **Config** | `config.yaml` (YAML) |
| **WebSocket Port** | 8443 (configurable) |
| **Metrics Port** | 9090 (configurable, optional) |
| **Build** | `make build` / `make release` |
| **Test** | `make test` / `go test ./...` |
| **Architecture** | Hub-and-Spoke broadcast pattern using Go channels |

---

## Documentation Files

### 📋 codebase_info.md
**What it contains:** Project metadata, directory tree, technology stack, build targets, and codebase statistics.  
**When to consult:** When you need to understand the project layout, find a file, or check what tools/languages are used.  
**Key topics:** Directory structure, Go module info, Makefile targets, dependency counts.

---

### 🏗️ architecture.md
**What it contains:** System design, Hub-and-Spoke pattern explanation, concurrency model, goroutine lifecycle, security model, and deployment architecture.  
**When to consult:** When you need to understand HOW the system works at a high level, the threading model, or how components interact.  
**Key topics:** CSP concurrency, fan-out broadcasting, TLS configuration, CI/CD pipeline structure.  
**Cross-references:** → `components.md` for implementation details, → `workflows.md` for sequence flows.

---

### 🧩 components.md
**What it contains:** Detailed description of each Go package — structs, methods, fields, and their responsibilities.  
**When to consult:** When you need to modify a specific package, understand a struct's fields, or find where functionality lives.  
**Key topics:** Hub struct and methods, Config struct, metrics variables, test coverage map.  
**Cross-references:** → `architecture.md` for design rationale, → `interfaces.md` for external contracts.

---

### 🔌 interfaces.md
**What it contains:** All external interfaces — WebSocket endpoint behavior, metrics endpoint, CLI flags, configuration schema, and integration points.  
**When to consult:** When you need to understand how clients interact with the server, what the API contract is, or how to configure the service.  
**Key topics:** WebSocket message protocol, Prometheus metric names, CLI usage, YAML config schema.  
**Cross-references:** → `data_models.md` for config struct details, → `components.md` for handler implementation.

---

### 📊 data_models.md
**What it contains:** All data structures — Config struct, Hub state, message format, metrics model, and connection state machine.  
**When to consult:** When you need to understand data shapes, struct definitions, channel types, or state transitions.  
**Key topics:** Config YAML mapping, Hub channels and their payloads, connection lifecycle states.  
**Cross-references:** → `interfaces.md` for how models are exposed externally, → `components.md` for methods operating on these models.

---

### 🔄 workflows.md
**What it contains:** Step-by-step process flows — startup, connection, broadcast, build/release, development, and error handling.  
**When to consult:** When you need to understand the sequence of operations, debug a flow, or add a new feature that hooks into an existing workflow.  
**Key topics:** Application startup sequence, client lifecycle, CI/CD pipeline steps, error handling paths.  
**Cross-references:** → `architecture.md` for the concurrency model underlying workflows, → `components.md` for method details.

---

### 📦 dependencies.md
**What it contains:** Complete dependency inventory — direct and transitive deps, their versions, usage locations, security considerations, and build tools.  
**When to consult:** When updating dependencies, evaluating security, understanding what libraries provide, or considering alternatives.  
**Key topics:** gorilla/websocket APIs used, Prometheus client usage, gopkg.in/yaml.v3 usage, transitive dependency tree.  
**Cross-references:** → `components.md` for where dependencies are imported.

---

### 📝 review_notes.md
**What it contains:** Documentation quality assessment — consistency issues, completeness gaps, bugs found during analysis, and prioritized recommendations.  
**When to consult:** When looking for known issues, potential bugs, or areas needing improvement.  
**Key topics:** Metrics type bug, port mismatch in example, missing features (graceful shutdown, rate limiting), test coverage gaps.  
**Cross-references:** All other files (identifies issues across the entire codebase).

---

## Quick Lookup: Common Questions

| Question | File to Consult |
|----------|----------------|
| "What does this project do?" | This file (index.md) |
| "Where is X implemented?" | `codebase_info.md` → directory tree |
| "How does the Hub work?" | `components.md` → Hub section |
| "What's the WebSocket message format?" | `interfaces.md` → WebSocket Endpoint |
| "How do I build/test?" | `codebase_info.md` → Build Targets |
| "What metrics are exposed?" | `interfaces.md` → Metrics Endpoint |
| "What are the config options?" | `interfaces.md` → Configuration Interface |
| "Are there known bugs?" | `review_notes.md` → Inconsistencies |
| "What should I improve?" | `review_notes.md` → Recommendations |
| "What dependencies does it use?" | `dependencies.md` |
| "How does startup work?" | `workflows.md` → Application Startup |
| "How are connections handled?" | `workflows.md` → Client Connection Workflow |
| "What's the threading model?" | `architecture.md` → Concurrency Model |