diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..7d38348
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,18 @@
+// Package main contains the RadChat application entrypoint and HTTP handlers.
+//
+// RadChat is a lightweight, self-hostable voice/text chat with WebRTC for
+// peer-to-peer media and WebSockets for control signaling. The package wires up
+// HTTP routes for:
+//   - /ws: WebSocket endpoint for signaling (join/leave, ICE, offers/answers, chat)
+//   - /user-count: Small health/info endpoint returning connected users
+//   - /check-username: Validate username rules and collision checks
+//   - /files: Upload endpoint for ephemeral file sharing
+//   - /files/{id}: Download endpoint for previously uploaded files
+//
+// Static assets are served from ./static and include the single-page app (SPA)
+// implemented in static/app.js.
+//
+// The main stateful coordination happens in the server subpackage via the Hub
+// and Client types. This package (
+// package main) creates, runs, and exposes that hub over HTTP.
+package main
diff --git a/server/doc.go b/server/doc.go
new file mode 100644
index 0000000..b9b394f
--- /dev/null
+++ b/server/doc.go
@@ -0,0 +1,12 @@
+// Package server contains the networking primitives for RadChat.
+//
+// It exposes:
+//   - Hub: central registry/bus of connected Clients with broadcast/register/unregister channels
+//   - Client: a single WebSocket connection/user state and its outbound send queue
+//   - Upgrader: an Origin-checking Gorilla WebSocket upgrader factory
+//   - Middleware: simple HTTP middleware for gzip and cache control
+//
+// The package is intentionally small: it focuses on safe concurrent access to
+// client maps and channels, and leaves higher-level HTTP routing and handlers in
+// the main package.
+package server