bzzz/README.md

# BZZZ: Distributed Semantic Context Publishing Platform

**Version 2.0 - Phase 2B Edition**

BZZZ is a production-ready, distributed platform for semantic context publishing with end-to-end encryption, role-based access control, and autonomous consensus mechanisms. It enables secure collaborative decision-making across distributed teams and AI agents.

## Key Features

- **🔐 End-to-End Encryption**: Age encryption with multi-recipient support
- **🏗️ Distributed Storage**: DHT-based storage with automatic replication
- **👥 Role-Based Access**: Hierarchical role system with inheritance
- **🗳️ Autonomous Consensus**: Automatic admin elections with Shamir secret sharing
- **🌐 P2P Networking**: Decentralized libp2p networking with peer discovery
- **📊 Real-Time Events**: WebSocket-based event streaming
- **🔧 Developer SDKs**: Complete SDKs for Go, Python, JavaScript, and Rust

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                      BZZZ Platform                             │
├─────────────────────────────────────────────────────────────────┤
│  API Layer: HTTP/WebSocket/MCP                                 │
│  Service Layer: Decision Publisher, Elections, Config          │
│  Infrastructure: Age Crypto, DHT Storage, P2P Network          │
└─────────────────────────────────────────────────────────────────┘
```

## Components

- **`main.go`** - Application entry point and server initialization
- **`api/`** - HTTP API handlers and WebSocket event streaming
- **`pkg/config/`** - Configuration management and role definitions
- **`pkg/crypto/`** - Age encryption and Shamir secret sharing
- **`pkg/dht/`** - Distributed hash table storage with caching
- **`pkg/ucxl/`** - UCXL addressing and decision publishing
- **`pkg/election/`** - Admin consensus and election management
- **`examples/`** - SDK examples in multiple programming languages
- **`docs/`** - Comprehensive documentation suite

## Quick Start

### Prerequisites

- **Go 1.23+** for building from source
- **Linux/macOS/Windows** - cross-platform support
- **Port 8080** - HTTP API (configurable)
- **Port 4001** - P2P networking (configurable)

### Installation

```bash
# Clone the repository
git clone https://github.com/anthonyrawlins/bzzz.git
cd bzzz

# Build the binary
go build -o bzzz main.go

# Run with default configuration
./bzzz
```

### Configuration

Create a configuration file:

```yaml
# config.yaml
node:
  id: "your-node-id"
  
agent:
  id: "your-agent-id" 
  role: "backend_developer"
  
api:
  host: "localhost"
  port: 8080
  
p2p:
  port: 4001
  bootstrap_peers: []
```

### First Steps

1. **Start the node**: `./bzzz --config config.yaml`
2. **Check status**: `curl http://localhost:8080/api/agent/status`
3. **Publish a decision**: See [User Manual](docs/USER_MANUAL.md#publishing-decisions)
4. **Explore the API**: See [API Reference](docs/API_REFERENCE.md)

For detailed setup instructions, see the **[User Manual](docs/USER_MANUAL.md)**.

## Documentation

Complete documentation is available in the [`docs/`](docs/) directory:

### 📚 **Getting Started**
- **[User Manual](docs/USER_MANUAL.md)** - Complete user guide with examples
- **[API Reference](docs/API_REFERENCE.md)** - HTTP API documentation
- **[Configuration Reference](docs/CONFIG_REFERENCE.md)** - System configuration

### 🔧 **For Developers**  
- **[Developer Guide](docs/DEVELOPER.md)** - Development setup and contribution
- **[SDK Documentation](docs/BZZZv2B-SDK.md)** - Multi-language SDK guide
- **[SDK Examples](examples/sdk/README.md)** - Working examples in Go, Python, JavaScript, Rust

### 🏗️ **Architecture & Operations**
- **[Architecture Documentation](docs/ARCHITECTURE.md)** - System design with diagrams  
- **[Technical Report](docs/TECHNICAL_REPORT.md)** - Comprehensive technical analysis
- **[Security Documentation](docs/SECURITY.md)** - Security model and best practices
- **[Operations Guide](docs/OPERATIONS.md)** - Deployment and monitoring

**📖 [Complete Documentation Index](docs/README.md)**

## SDK & Integration

BZZZ provides comprehensive SDKs for multiple programming languages:

### Go SDK
```go
import "github.com/anthonyrawlins/bzzz/sdk/bzzz"

client, err := bzzz.NewClient(bzzz.Config{
    Endpoint: "http://localhost:8080",
    Role:     "backend_developer",
})
```

### Python SDK  
```python
from bzzz_sdk import BzzzClient

client = BzzzClient(
    endpoint="http://localhost:8080",
    role="backend_developer"
)
```

### JavaScript SDK
```javascript  
const { BzzzClient } = require('bzzz-sdk');

const client = new BzzzClient({
    endpoint: 'http://localhost:8080',
    role: 'frontend_developer'
});
```

### Rust SDK
```rust
use bzzz_sdk::{BzzzClient, Config};

let client = BzzzClient::new(Config {
    endpoint: "http://localhost:8080".to_string(),
    role: "backend_developer".to_string(),
    ..Default::default()
}).await?;
```

**See [SDK Examples](examples/sdk/README.md) for complete working examples.**

## Key Use Cases

### 🤖 **AI Agent Coordination**
- Multi-agent decision publishing and consensus
- Secure inter-agent communication with role-based access
- Autonomous coordination with admin elections

### 🏢 **Enterprise Collaboration**  
- Secure decision tracking across distributed teams
- Hierarchical access control for sensitive information
- Audit trails for compliance and governance

### 🔧 **Development Teams**
- Collaborative code review and architecture decisions  
- Integration with CI/CD pipelines and development workflows
- Real-time coordination across development teams

### 📊 **Research & Analysis**
- Secure sharing of research findings and methodologies
- Collaborative analysis with access controls
- Distributed data science workflows

## Security & Privacy

- **🔐 End-to-End Encryption**: All decision content encrypted with Age
- **🔑 Key Management**: Automatic key generation and rotation
- **👥 Access Control**: Role-based permissions with hierarchy
- **🛡️ Admin Security**: Shamir secret sharing for admin key recovery
- **📋 Audit Trail**: Complete audit logging for all operations
- **🚫 Zero Trust**: No central authority required for normal operations

## Performance & Scalability

- **⚡ Fast Operations**: Sub-500ms latency for 95% of operations
- **📈 Horizontal Scaling**: Linear scaling up to 1000+ nodes
- **🗄️ Efficient Storage**: DHT-based distributed storage with caching
- **🌐 Global Distribution**: P2P networking with cross-region support
- **📊 Real-time Updates**: WebSocket event streaming for live updates

## Contributing

We welcome contributions! Please see the **[Developer Guide](docs/DEVELOPER.md)** for:

- Development environment setup
- Code style and contribution guidelines  
- Testing procedures and requirements
- Documentation standards

### Quick Contributing Steps
1. **Fork** the repository
2. **Clone** your fork locally  
3. **Follow** the [Developer Guide](docs/DEVELOPER.md#development-environment)
4. **Create** a feature branch
5. **Test** your changes thoroughly
6. **Submit** a pull request

## License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

## Support

- **📖 Documentation**: [docs/README.md](docs/README.md)
- **🐛 Issues**: [GitHub Issues](https://github.com/anthonyrawlins/bzzz/issues)
- **💬 Discussions**: [GitHub Discussions](https://github.com/anthonyrawlins/bzzz/discussions)
- **📧 Contact**: [maintainers@bzzz.dev](mailto:maintainers@bzzz.dev)

---

**BZZZ v2.0** - Distributed Semantic Context Publishing Platform with Age encryption and autonomous consensus.