Add detailed godoc documentation to CLIEntry function

Expand the documentation comment for CLIEntry to provide more context
about what the function does, including its use of the fx dependency
injection framework, signal handling, and blocking behavior.

internal/routewatch/ashandler.go

@@ -22,7 +22,10 @@ const (
 	asnBatchTimeout = 2 * time.Second
 )
 
-// ASHandler handles ASN information from BGP messages using batched operations
+// ASHandler processes Autonomous System Number (ASN) information extracted from
+// BGP UPDATE messages. It uses batched database operations to efficiently store
+// ASN data, collecting operations into batches that are flushed either when the
+// batch reaches a size threshold or after a timeout period.
 type ASHandler struct {
 	db     database.Store
 	logger *logger.Logger
@@ -40,7 +43,11 @@ type asnOp struct {
 	timestamp time.Time
 }
 
-// NewASHandler creates a new batched ASN handler
+// NewASHandler creates and returns a new ASHandler instance. It initializes
+// the batching system and starts a background goroutine that periodically
+// flushes accumulated ASN operations to the database. The caller must call
+// Stop when finished to ensure all pending operations are flushed and the
+// background goroutine is terminated.
 func NewASHandler(db database.Store, logger *logger.Logger) *ASHandler {
 	h := &ASHandler{
 		db:        db,
@@ -57,19 +64,27 @@ func NewASHandler(db database.Store, logger *logger.Logger) *ASHandler {
 	return h
 }
 
-// WantsMessage returns true if this handler wants to process messages of the given type
+// WantsMessage reports whether this handler should process messages of the
+// given type. ASHandler only processes "UPDATE" messages, as these contain
+// the AS path information needed to track autonomous systems.
 func (h *ASHandler) WantsMessage(messageType string) bool {
 	// We only care about UPDATE messages for the database
 	return messageType == "UPDATE"
 }
 
-// QueueCapacity returns the desired queue capacity for this handler
+// QueueCapacity returns the recommended message queue size for this handler.
+// ASHandler uses a large queue capacity to accommodate high-volume BGP streams,
+// as the batching mechanism allows efficient processing of accumulated messages.
 func (h *ASHandler) QueueCapacity() int {
 	// Batching allows us to use a larger queue
 	return asHandlerQueueSize
 }
 
-// HandleMessage processes a RIS message and queues database operations
+// HandleMessage processes a RIS Live BGP message by extracting all ASNs from
+// the AS path and queuing them for batch insertion into the database. The
+// origin ASN (last element in the path) and all transit ASNs are recorded
+// with their associated timestamps. The batch is automatically flushed when
+// it reaches the configured size threshold.
 func (h *ASHandler) HandleMessage(msg *ristypes.RISMessage) {
 	// Use the pre-parsed timestamp
 	timestamp := msg.ParsedTimestamp

internal/routewatch/cli.go

@@ -53,7 +53,11 @@ func logDebugStats(logger *logger.Logger) {
 	}
 }
 
-// CLIEntry is the main entry point for the CLI
+// CLIEntry is the main entry point for the routewatch command-line interface.
+// It initializes the application using the fx dependency injection framework,
+// sets up signal handling for graceful shutdown, and starts the RouteWatch service.
+// This function blocks until the application receives a shutdown signal or encounters
+// a fatal error.
 func CLIEntry() {
 	app := fx.New(
 		getModule(),

internal/routewatch/handler.go

@@ -5,14 +5,20 @@ import (
 	"git.eeqj.de/sneak/routewatch/internal/ristypes"
 )
 
-// SimpleHandler is a basic implementation of streamer.MessageHandler
+// SimpleHandler is a basic implementation of streamer.MessageHandler that
+// filters messages by type and delegates processing to a callback function.
+// It provides a simple way to handle specific RIS message types without
+// implementing the full MessageHandler interface from scratch.
 type SimpleHandler struct {
 	logger       *logger.Logger
 	messageTypes []string
 	callback     func(*ristypes.RISMessage)
 }
 
-// NewSimpleHandler creates a handler that accepts specific message types
+// NewSimpleHandler creates a new SimpleHandler that accepts specific message types.
+// The messageTypes parameter specifies which RIS message types this handler will process.
+// If messageTypes is empty, the handler will accept all message types.
+// The callback function is invoked for each message that passes the type filter.
 func NewSimpleHandler(
 	logger *logger.Logger,
 	messageTypes []string,
@@ -25,7 +31,9 @@ func NewSimpleHandler(
 	}
 }
 
-// WantsMessage returns true if this handler wants to process messages of the given type
+// WantsMessage returns true if this handler wants to process messages of the given type.
+// It checks whether messageType is in the handler's configured list of accepted types.
+// If no specific types were configured (empty messageTypes slice), it returns true for all types.
 func (h *SimpleHandler) WantsMessage(messageType string) bool {
 	// If no specific types are set, accept all messages
 	if len(h.messageTypes) == 0 {
@@ -41,7 +49,8 @@ func (h *SimpleHandler) WantsMessage(messageType string) bool {
 	return false
 }
 
-// HandleMessage processes a RIS message
+// HandleMessage processes a RIS message by invoking the configured callback function.
+// If no callback was provided during construction, the message is silently ignored.
 func (h *SimpleHandler) HandleMessage(msg *ristypes.RISMessage) {
 	if h.callback != nil {
 		h.callback(msg)

internal/routewatch/peerhandler.go

@@ -1,5 +1,8 @@
 package routewatch
 
+// peerhandler.go provides batched peer tracking functionality for BGP route monitoring.
+// It tracks BGP peers from all incoming RIS messages and maintains peer state in the database.
+
 import (
 	"strconv"
 	"sync"
@@ -21,7 +24,10 @@ const (
 	peerBatchTimeout = 2 * time.Second
 )
 
-// PeerHandler tracks BGP peers from all message types using batched operations
+// PeerHandler tracks BGP peers from all message types using batched operations.
+// It maintains a queue of peer updates and periodically flushes them to the database
+// in batches to improve performance. The handler deduplicates peer updates within
+// each batch, keeping only the most recent update for each peer IP address.
 type PeerHandler struct {
 	db     database.Store
 	logger *logger.Logger

internal/routewatch/peeringhandler.go

@@ -11,23 +11,36 @@ import (
 )
 
 const (
-	// peeringHandlerQueueSize is the queue capacity for peering operations
+	// peeringHandlerQueueSize defines the buffer capacity for the peering
+	// handler's message queue. This should be large enough to handle bursts
+	// of BGP UPDATE messages without blocking.
 	peeringHandlerQueueSize = 100000
 
-	// minPathLengthForPeering is the minimum AS path length to extract peerings
+	// minPathLengthForPeering specifies the minimum number of ASNs required
+	// in a BGP AS path to extract peering relationships. A path with fewer
+	// than 2 ASNs cannot contain any peering information.
 	minPathLengthForPeering = 2
 
-	// pathExpirationTime is how long to keep AS paths in memory
+	// pathExpirationTime determines how long AS paths are kept in memory
+	// before being eligible for pruning. Paths older than this are removed
+	// to prevent unbounded memory growth.
 	pathExpirationTime = 30 * time.Minute
 
-	// peeringProcessInterval is how often to process AS paths into peerings
+	// peeringProcessInterval controls how frequently the handler processes
+	// accumulated AS paths and extracts peering relationships to store
+	// in the database.
 	peeringProcessInterval = 30 * time.Second
 
-	// pathPruneInterval is how often to prune old AS paths
+	// pathPruneInterval determines how often the handler checks for and
+	// removes expired AS paths from memory.
 	pathPruneInterval = 5 * time.Minute
 )
 
-// PeeringHandler handles AS peering relationships from BGP path data
+// PeeringHandler processes BGP UPDATE messages to extract and track
+// AS peering relationships. It accumulates AS paths in memory and
+// periodically processes them to extract unique peering pairs, which
+// are then stored in the database. The handler implements the Handler
+// interface for integration with the message processing pipeline.
 type PeeringHandler struct {
 	db     database.Store
 	logger *logger.Logger
@@ -39,7 +52,11 @@ type PeeringHandler struct {
 	stopCh chan struct{}
 }
 
-// NewPeeringHandler creates a new batched peering handler
+// NewPeeringHandler creates and initializes a new PeeringHandler with the
+// provided database store and logger. It starts two background goroutines:
+// one for periodic processing of accumulated AS paths into peering records,
+// and one for pruning expired paths from memory. The handler begins
+// processing immediately upon creation.
 func NewPeeringHandler(db database.Store, logger *logger.Logger) *PeeringHandler {
 	h := &PeeringHandler{
 		db:      db,