From 3dc0ac0728723225163ae2d11feeae8c4114ccb5 Mon Sep 17 00:00:00 2001
From: Houmgaor <contact@houmgaor.com>
Date: Mon, 23 Feb 2026 18:09:08 +0100
Subject: [PATCH] docs: expand doc.go for channelserver and mhfpacket packages

Document the Unk field naming convention used across 300+ packet
structs so new contributors understand these are intentionally
unnamed reverse-engineered protocol fields. Expand channelserver
doc.go with handler registration workflow, repository pattern,
testing approach, and lock ordering.
---
 network/mhfpacket/doc.go    | 10 ++++++++++
 server/channelserver/doc.go | 37 +++++++++++++++++++++++++++++++++++--
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/network/mhfpacket/doc.go b/network/mhfpacket/doc.go
index 5787a3952..a911ddeb0 100644
--- a/network/mhfpacket/doc.go
+++ b/network/mhfpacket/doc.go
@@ -1,4 +1,14 @@
 // Package mhfpacket defines the struct representations and binary
 // serialization for every MHF network packet (~400 message types). Each
 // packet implements the [MHFPacket] interface (Parse, Build, Opcode).
+//
+// # Unk Fields
+//
+// Fields named Unk0, Unk1, … UnkN (or simply Unk) are protocol fields
+// whose purpose has not yet been reverse-engineered. They are parsed and
+// round-tripped faithfully but their semantic meaning is unknown. As
+// fields are identified through protocol research or client
+// decompilation, they should be renamed to descriptive names. The same
+// convention applies to Unk fields in handler and repository code
+// throughout the channelserver package.
 package mhfpacket
diff --git a/server/channelserver/doc.go b/server/channelserver/doc.go
index e44f2a699..38d0dcac5 100644
--- a/server/channelserver/doc.go
+++ b/server/channelserver/doc.go
@@ -3,9 +3,42 @@
 // player sessions, stage (lobby/quest room) state, guild operations, item
 // management, event systems, and binary state relay between clients.
 //
+// # Handler Organization
+//
 // Packet handlers are organized by game system into separate files
-// (handlers_quest.go, handlers_guild.go, etc.) and registered in
-// handlers_table.go. Each handler has the signature:
+// (handlers_quest.go, handlers_guild.go, etc.) and registered via
+// [buildHandlerTable] in handlers_table.go. Each handler has the signature:
 //
 //	func(s *Session, p mhfpacket.MHFPacket)
+//
+// To add a new handler:
+//  1. Define the packet struct in network/mhfpacket/msg_*.go
+//  2. Add an entry in [buildHandlerTable] mapping the opcode to the handler
+//  3. Implement the handler in the appropriate handlers_*.go file
+//
+// # Repository Pattern
+//
+// All database access goes through interface-based repositories defined in
+// repo_interfaces.go. The [Server] struct holds interface types, not concrete
+// implementations. Concrete PostgreSQL implementations live in repo_*.go
+// files. Mock implementations in repo_mocks_test.go enable unit tests
+// without a database.
+//
+// Handler code must never contain inline SQL — use the appropriate repo
+// method. If a query doesn't exist yet, add it to the relevant repo file
+// and its interface.
+//
+// # Testing
+//
+// Tests use mock repositories (repo_mocks_test.go) and shared test helpers
+// (test_helpers_test.go). The standard pattern is table-driven tests; see
+// handlers_achievement_test.go for a typical example. Always run tests with
+// the race detector: go test -race ./...
+//
+// # Concurrency
+//
+// Lock ordering: Server.Mutex → Stage.RWMutex → semaphoreLock.
+// The stage map uses sync.Map for lock-free concurrent access; individual
+// Stage structs have their own sync.RWMutex. Cross-channel operations go
+// exclusively through the [ChannelRegistry] interface.
 package channelserver