hash-of-wisdom/docs/PACKAGES.md

Package Structure

This document explains the organization and responsibilities of all packages in the Hash of Wisdom project.

Directory Structure

/
├── cmd/                    # Application entry points
│   ├── server/            # Server application
│   └── client/            # Client application
├── internal/              # Private application packages
│   ├── application/      # Application layer (message handling)
│   ├── config/           # Configuration management
│   ├── lib/              # Shared utilities
│   ├── metrics/          # Prometheus metrics
│   ├── pow/              # Proof-of-Work implementation
│   ├── protocol/         # Binary protocol codec
│   ├── quotes/           # Quote service
│   ├── server/           # TCP server implementation
│   └── service/          # Business logic layer
├── test/                 # Integration tests
└── docs/                 # Documentation

Package Responsibilities

cmd/server

Entry point for the TCP server application

• Parses command-line flags and configuration
• Initializes all components with dependency injection
• Starts TCP server and metrics endpoints
• Handles graceful shutdown signals

cmd/client

Entry point for the client application

• Command-line interface for connecting to server
• Handles proof-of-work solving on client side
• Manages TCP connection lifecycle

internal/config

Configuration management with cleanenv

• Defines configuration structures with YAML/env tags
• Loads configuration from files and environment variables
• Provides sensible defaults for all settings
• Supports both development and production configurations

internal/lib/sl

Shared logging utilities

• Structured logging helpers for consistent log formatting
• Error attribute helpers for slog integration

internal/metrics

Prometheus metrics collection

• Defines application-specific metrics (requests, errors, duration)
• Provides simple counters and histograms for monitoring
• Integrated at the infrastructure layer (TCP server)

internal/pow

Proof-of-Work implementation

internal/pow/challenge

• Challenge Generation: Creates HMAC-signed stateless challenges
• Verification: Validates solutions against original challenges
• Security: HMAC authentication prevents tampering
• Configuration: Difficulty scaling, TTL management, secrets

internal/pow/solver

• Solution Finding: Brute-force nonce search with SHA-256
• Optimization: Efficient bit counting for difficulty verification
• Client-side: Used by client to solve server challenges

internal/protocol

Binary protocol codec

• Message Types: Challenge requests/responses, solution requests/responses, errors
• Encoding/Decoding: JSON-based message serialization
• Streaming: MessageDecoder for reading from TCP connections
• Validation: Message structure and field validation
• See Protocol Specification for detailed message flow and format

internal/quotes

Quote service implementation

• HTTP Client: Fetches quotes from external APIs using resty
• Interface: Clean abstraction for quote retrieval
• Error Handling: Graceful degradation for network issues
• Timeout Management: Configurable request timeouts

internal/server

TCP server implementation

internal/server/tcp.go

• Connection Management: Accept, handle, cleanup TCP connections
• Protocol Integration: Uses protocol package for message handling
• Security: Connection timeouts, slowloris protection
• Metrics: Request tracking at infrastructure layer
• Lifecycle: Graceful startup/shutdown with context

internal/server/config.go

• Server Configuration: Network settings, timeouts
• Functional Options: Builder pattern for server customization

internal/application

Application layer (message handling and coordination)

• WisdomApplication: Protocol message handler and coordinator
• Message Processing: Handles challenge and solution requests from protocol layer
• Response Generation: Creates appropriate protocol responses
• Service Coordination: Orchestrates calls to business logic layer
• Error Handling: Converts service errors to protocol error responses

internal/service

Business logic layer (core domain services)

• WisdomService: Main business logic coordinator
• Challenge Workflow: Manages challenge generation and validation
• Solution Workflow: Handles solution verification and quote retrieval
• Clean Architecture: Pure business logic, no I/O dependencies
• Testing: Easily mockable interfaces for unit testing

Service Dependencies:

• ChallengeGenerator - Creates new challenges
• ChallengeVerifier - Validates submitted solutions
• QuoteService - Retrieves quotes after successful validation

test/integration

End-to-end integration tests

• Slowloris Protection: Tests server resilience against slow attacks
• Connection Timeouts: Validates timeout configurations
• Full Workflow: Tests complete client-server interaction
• Real Components: Uses actual TCP connections and protocol

Dependency Flow

cmd/server
    ↓
internal/config → internal/server → internal/application → internal/service
                      ↓                    ↓                   ↓
                internal/protocol     internal/protocol   internal/pow
                internal/metrics                         internal/quotes

Architecture Benefits

This package structure provides:

• Clear Separation: Each package has a single, well-defined responsibility
• Testability: Dependencies are injected, making testing straightforward
• Maintainability: Changes are isolated to specific layers
• Scalability: Clean interfaces allow for easy implementation swapping