Add godoc documentation and README with code structure

Add comprehensive godoc comments to all exported types, functions,
and constants throughout the codebase. Create README.md documenting
the project architecture, execution flow, database schema, and
component relationships.

internal/streamer/streamer.go

@@ -56,7 +56,8 @@ type MessageHandler interface {
 	QueueCapacity() int
 }
 
-// RawMessageHandler is a callback for handling raw JSON lines from the stream
+// RawMessageHandler is a function type for processing raw JSON lines from the stream.
+// It receives the unmodified JSON line as a string before any parsing occurs.
 type RawMessageHandler func(line string)
 
 // handlerMetrics tracks performance metrics for a handler
@@ -77,7 +78,10 @@ type handlerInfo struct {
 	metrics handlerMetrics
 }
 
-// Streamer handles streaming BGP updates from RIS Live
+// Streamer manages a connection to the RIPE RIS Live streaming API for receiving
+// real-time BGP UPDATE messages. It handles automatic reconnection with exponential
+// backoff, dispatches messages to registered handlers via per-handler queues, and
+// implements backpressure to prevent queue overflow during high traffic periods.
 type Streamer struct {
 	logger       *logger.Logger
 	client       *http.Client
@@ -91,7 +95,9 @@ type Streamer struct {
 	random       *rand.Rand // Random number generator for backpressure drops
 }
 
-// New creates a new RIS streamer
+// New creates a new Streamer instance configured to connect to the RIS Live API.
+// The logger is used for structured logging of connection events and errors.
+// The metrics tracker is used to record message counts, bytes received, and connection status.
 func New(logger *logger.Logger, metrics *metrics.Tracker) *Streamer {
 	return &Streamer{
 		logger: logger,
@@ -105,7 +111,9 @@ func New(logger *logger.Logger, metrics *metrics.Tracker) *Streamer {
 	}
 }
 
-// RegisterHandler adds a callback for message processing
+// RegisterHandler adds a MessageHandler to receive parsed RIS messages.
+// Each handler gets its own dedicated queue and worker goroutine for processing.
+// If the streamer is already running, the handler's worker is started immediately.
 func (s *Streamer) RegisterHandler(handler MessageHandler) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -127,14 +135,19 @@ func (s *Streamer) RegisterHandler(handler MessageHandler) {
 	}
 }
 
-// RegisterRawHandler sets a callback for raw message lines
+// RegisterRawHandler sets a callback to receive raw JSON lines from the stream
+// before they are parsed. Only one raw handler can be registered at a time;
+// subsequent calls will replace the previous handler.
 func (s *Streamer) RegisterRawHandler(handler RawMessageHandler) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	s.rawHandler = handler
 }
 
-// Start begins streaming in a goroutine
+// Start begins streaming BGP updates from the RIS Live API in a background goroutine.
+// It starts worker goroutines for each registered handler and manages automatic
+// reconnection with exponential backoff on connection failures.
+// Returns an error if the streamer is already running.
 func (s *Streamer) Start() error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -162,7 +175,9 @@ func (s *Streamer) Start() error {
 	return nil
 }
 
-// Stop halts the streaming
+// Stop halts the streaming connection and shuts down all handler workers.
+// It cancels the streaming context, closes all handler queues, and updates
+// the connection status in metrics. This method is safe to call multiple times.
 func (s *Streamer) Stop() {
 	s.mu.Lock()
 	if s.cancel != nil {
@@ -202,7 +217,8 @@ func (s *Streamer) runHandlerWorker(info *handlerInfo) {
 	}
 }
 
-// IsRunning returns whether the streamer is currently active
+// IsRunning reports whether the streamer is currently connected and processing messages.
+// This is safe to call concurrently from multiple goroutines.
 func (s *Streamer) IsRunning() bool {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
@@ -210,17 +226,21 @@ func (s *Streamer) IsRunning() bool {
 	return s.running
 }
 
-// GetMetrics returns current streaming metrics
+// GetMetrics returns the current streaming metrics including message counts,
+// bytes received, and throughput rates. The returned struct is a snapshot
+// of the current state and is safe to use without synchronization.
 func (s *Streamer) GetMetrics() metrics.StreamMetrics {
 	return s.metrics.GetStreamMetrics()
 }
 
-// GetMetricsTracker returns the metrics tracker instance
+// GetMetricsTracker returns the underlying metrics.Tracker instance for direct access
+// to metrics recording and retrieval functionality.
 func (s *Streamer) GetMetricsTracker() *metrics.Tracker {
 	return s.metrics
 }
 
-// HandlerStats represents metrics for a single handler
+// HandlerStats contains performance metrics for a single message handler.
+// It includes queue utilization, message counts, and processing time statistics.
 type HandlerStats struct {
 	Name               string
 	QueueLength        int
@@ -233,7 +253,9 @@ type HandlerStats struct {
 	MaxProcessTime     time.Duration
 }
 
-// GetHandlerStats returns current handler statistics
+// GetHandlerStats returns a snapshot of performance statistics for all registered
+// handlers. The returned slice contains one HandlerStats entry per handler with
+// current queue depth, processed/dropped counts, and processing time statistics.
 func (s *Streamer) GetHandlerStats() []HandlerStats {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
@@ -273,7 +295,9 @@ func (s *Streamer) GetHandlerStats() []HandlerStats {
 	return stats
 }
 
-// GetDroppedMessages returns the total number of dropped messages
+// GetDroppedMessages returns the total number of messages dropped across all handlers
+// due to queue overflow or backpressure. This counter is monotonically increasing
+// and is safe to call concurrently.
 func (s *Streamer) GetDroppedMessages() uint64 {
 	return atomic.LoadUint64(&s.totalDropped)
 }