hash-of-wisdom/README.md

# Hash of Wisdom

A TCP server implementing the "Word of Wisdom" concept with proof-of-work challenges to protect against DDoS attacks.

## Overview

The Hash of Wisdom server requires clients to solve computational puzzles (proof-of-work) before receiving wise quotes. This approach prevents spam and DDoS attacks by requiring clients to invest CPU time for each request.

## Quick Start

### Prerequisites
- Go 1.24.3+
- Docker (optional)
- [Task](https://taskfile.dev/) (optional, but recommended)

### Building
```bash
# Build server
go build -o hash-of-wisdom ./cmd/server

# Build client
go build -o client ./cmd/client
```

### Running

#### Using Task (Recommended)
```bash
# Most useful command - run all checks
task check

# Start server
task server -- -config config.yaml

# Connect client
task client -- --addr=localhost:8080

# Run tests
task test

# See coverage
task test-coverage

# See all available commands
task --list
```

#### Manual Commands
```bash
# Start server (uses config.yaml by default)
./hash-of-wisdom

# Or with custom config
./hash-of-wisdom -config /path/to/config.yaml

# Connect with client
./client -addr localhost:8080

# Run tests
go test ./...
```

### Using Docker
```bash
# Build image
docker build -t hash-of-wisdom .

# Run container
docker run -p 8080:8080 -p 8081:8081 hash-of-wisdom
```

### Monitoring
- Metrics: http://localhost:8081/metrics (Prometheus format with Go runtime stats)
- Profiling: http://localhost:8081/debug/pprof/

## Documentation

### Protocol & Implementation
- [Protocol Specification](docs/PROTOCOL.md) - Binary protocol definition
- [PoW Algorithm Analysis](docs/POW_ANALYSIS.md) - Algorithm selection rationale and comparison
- [Implementation Plan](docs/IMPLEMENTATION.md) - Development phases and progress
- [Package Structure](docs/PACKAGES.md) - Code organization and package responsibilities
- [Architecture Choices](docs/ARCHITECTURE.md) - Design decisions and patterns

### Production Readiness
- [Production Readiness Guide](docs/PRODUCTION_READINESS.md) - Requirements for production deployment