Initial commit

README.md

@@ -0,0 +1,124 @@
+# BTClock Go Server
+
+A high-performance data service for the BTClock, providing real-time Bitcoin data through WebSocket connections.
+
+## Features
+
+- Real-time Bitcoin price updates
+- Mempool fee rate monitoring
+- Block height tracking
+- WebSocket API (v1 and v2)
+- Docker support
+- Graceful shutdown handling
+- Modular architecture
+
+## Prerequisites
+
+- Go 1.21 or later
+- Docker and Docker Compose (optional)
+
+## Installation
+
+### Local Development
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/btclock-go-server.git
+cd btclock-go-server
+```
+
+2. Install dependencies:
+```bash
+go mod download
+```
+
+3. Run the server:
+```bash
+go run main.go
+```
+
+### Docker Deployment
+
+1. Build and run using Docker Compose:
+```bash
+docker-compose up --build
+```
+
+## Configuration
+
+The server can be configured using environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT | Server port | 80 |
+
+## API Documentation
+
+### WebSocket API v2
+
+Connect to `ws://your-server/api/v2/ws` for the latest API version.
+
+#### Subscribe to Events
+
+Send a binary message with the following structure:
+
+```json
+{
+  "type": "subscribe",
+  "eventType": "price",
+  "currencies": ["USD", "EUR"]
+}
+```
+
+Available event types:
+- `price`: Bitcoin price updates
+- `mempool-fee-rate`: Mempool fee rate updates
+- `mempool-block`: New block notifications
+
+#### Unsubscribe from Events
+
+```json
+{
+  "type": "unsubscribe",
+  "eventType": "price",
+  "currencies": ["USD", "EUR"]
+}
+```
+
+### WebSocket API v1
+
+Connect to `ws://your-server/api/v1/ws` for the legacy API version.
+
+Automatically subscribes to:
+- `blockheight-v1`: Block height updates
+- `blockfee-v1`: Fee rate updates
+- `price-v1`: Price updates
+
+## Project Structure
+
+```
+.
+├── broker/         # Event broker implementation
+├── clients/        # External service clients
+├── handlers/       # WebSocket request handlers
+├── models/         # Data models
+├── modules/        # Service modules
+├── static/         # Static web assets
+├── websocket/      # WebSocket utilities
+├── main.go         # Application entry point
+├── Dockerfile      # Docker configuration
+└── docker-compose.yaml
+```
+
+## Development
+
+### Testing
+
+Run the test suite:
+```bash
+go test ./...
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.