ee6bb09511
🎉 MAJOR MILESTONE: Complete BZZZ Phase 2B documentation and core implementation ## Documentation Suite (7,000+ lines) - ✅ User Manual: Comprehensive guide with practical examples - ✅ API Reference: Complete REST API documentation - ✅ SDK Documentation: Multi-language SDK guide (Go, Python, JS, Rust) - ✅ Developer Guide: Development setup and contribution procedures - ✅ Architecture Documentation: Detailed system design with ASCII diagrams - ✅ Technical Report: Performance analysis and benchmarks - ✅ Security Documentation: Comprehensive security model - ✅ Operations Guide: Production deployment and monitoring - ✅ Documentation Index: Cross-referenced navigation system ## SDK Examples & Integration - 🔧 Go SDK: Simple client, event streaming, crypto operations - 🐍 Python SDK: Async client with comprehensive examples - 📜 JavaScript SDK: Collaborative agent implementation - 🦀 Rust SDK: High-performance monitoring system - 📖 Multi-language README with setup instructions ## Core Implementation - 🔐 Age encryption implementation (pkg/crypto/age_crypto.go) - 🗂️ Shamir secret sharing (pkg/crypto/shamir.go) - 💾 DHT encrypted storage (pkg/dht/encrypted_storage.go) - 📤 UCXL decision publisher (pkg/ucxl/decision_publisher.go) - 🔄 Updated main.go with Phase 2B integration ## Project Organization - 📂 Moved legacy docs to old-docs/ directory - 🎯 Comprehensive README.md update with modern structure - 🔗 Full cross-reference system between all documentation - 📊 Production-ready deployment procedures ## Quality Assurance - ✅ All documentation cross-referenced and validated - ✅ Working code examples in multiple languages - ✅ Production deployment procedures tested - ✅ Security best practices implemented - ✅ Performance benchmarks documented Ready for production deployment and community adoption. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1009 lines
69 KiB
Markdown
1009 lines
69 KiB
Markdown
# BZZZ Architecture Documentation
|
|
|
|
**Version 2.0 - Phase 2B Edition**
|
|
**Comprehensive architectural analysis with detailed system diagrams**
|
|
|
|
## Table of Contents
|
|
|
|
1. [High-Level Architecture](#high-level-architecture)
|
|
2. [Component Architecture](#component-architecture)
|
|
3. [Data Flow Diagrams](#data-flow-diagrams)
|
|
4. [Network Architecture](#network-architecture)
|
|
5. [Security Architecture](#security-architecture)
|
|
6. [Deployment Architecture](#deployment-architecture)
|
|
7. [Integration Patterns](#integration-patterns)
|
|
|
|
## High-Level Architecture
|
|
|
|
### System Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ BZZZ SYSTEM │
|
|
│ Distributed Semantic Context │
|
|
│ Publishing Platform │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────┐
|
|
│ External │
|
|
│ Applications │
|
|
│ │
|
|
│ • Web UIs │
|
|
│ • Mobile Apps │
|
|
│ • CLI Tools │
|
|
│ • 3rd Party │
|
|
└─────────────────┘
|
|
│
|
|
╔═══════════▼═══════════╗
|
|
║ API LAYER ║
|
|
║ ║
|
|
║ ┌─────┐ ┌─────┐ ┌───┐ ║
|
|
║ │HTTP │ │WS │ │MCP│ ║
|
|
║ │API │ │Event│ │ │ ║
|
|
║ └─────┘ └─────┘ └───┘ ║
|
|
╚═══════════════════════╝
|
|
│
|
|
╔═══════════▼═══════════╗
|
|
║ SERVICE LAYER ║
|
|
║ ║
|
|
║ ┌─────────────────────┐ ║
|
|
║ │ Decision Publisher │ ║
|
|
║ ├─────────────────────┤ ║
|
|
║ │ Election Manager │ ║
|
|
║ ├─────────────────────┤ ║
|
|
║ │ Config Manager │ ║
|
|
║ ├─────────────────────┤ ║
|
|
║ │ Debug Tools │ ║
|
|
║ └─────────────────────┘ ║
|
|
╚═══════════════════════╝
|
|
│
|
|
╔═══════════▼═══════════╗
|
|
║ INFRASTRUCTURE LAYER ║
|
|
║ ║
|
|
║ ┌─────┐ ┌─────┐ ┌───┐ ║
|
|
║ │Crypto│ │ DHT │ │P2P│ ║
|
|
║ │ Age │ │Store│ │Net│ ║
|
|
║ │Shamir│ │Cache│ │Sub│ ║
|
|
║ └─────┘ └─────┘ └───┘ ║
|
|
╚═══════════════════════╝
|
|
```
|
|
|
|
### Layer Responsibilities
|
|
|
|
#### API Layer
|
|
- **HTTP API**: RESTful endpoints for decision CRUD operations
|
|
- **WebSocket Events**: Real-time event streaming and notifications
|
|
- **MCP Integration**: Model Context Protocol for AI agent integration
|
|
- **GraphQL**: Advanced querying capabilities (future)
|
|
|
|
#### Service Layer
|
|
- **Decision Publisher**: Core decision publishing and retrieval logic
|
|
- **Election Manager**: Admin election and consensus management
|
|
- **Config Manager**: Role and system configuration management
|
|
- **Debug Tools**: Development and operational debugging utilities
|
|
|
|
#### Infrastructure Layer
|
|
- **Crypto Module**: Age encryption and Shamir secret sharing
|
|
- **DHT Storage**: Distributed storage with caching and replication
|
|
- **P2P Network**: Peer discovery, connectivity, and pub/sub messaging
|
|
|
|
## Component Architecture
|
|
|
|
### Detailed Component Diagram
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ BZZZ COMPONENTS │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ main.go │────│ api/handlers │────│ api/server │
|
|
│ │ │ │ │ │
|
|
│ • App startup │ │ • Route handlers│ │ • HTTP server │
|
|
│ • Config load │ │ • Validation │ │ • Middleware │
|
|
│ • Graceful stop │ │ • Response fmt │ │ • WebSocket │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ pkg/ MODULES │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
|
|
│ │ config/ │ │ ucxl/ │ │ election/ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ • Config │ │ • Address │ │ • Election │ │
|
|
│ │ • Roles │ │ • Publisher │ │ • Consensus │ │
|
|
│ │ • Validation │ │ • Metadata │ │ • Heartbeat │ │
|
|
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
|
|
│ │ crypto/ │ │ dht/ │ │ ucxi/ │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ • AgeCrypto │ │ • Storage │ │ • Server │ │
|
|
│ │ • ShamirShares │ │ • Cache │ │ • Interface │ │
|
|
│ │ • KeyGeneration │ │ • Replication │ │ • Content │ │
|
|
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Component Interactions
|
|
|
|
```
|
|
Decision Publishing Flow:
|
|
========================
|
|
|
|
Client Request
|
|
│
|
|
▼
|
|
┌─────────────────┐ validate() ┌─────────────────┐
|
|
│ HTTP Handler │─────────────────▶│ Config Manager │
|
|
│ (decisions/) │ │ (role check) │
|
|
└─────────────────┘ └─────────────────┘
|
|
│ │
|
|
│ publish() ▼ getRoleKeys()
|
|
▼ ┌─────────────────┐
|
|
┌─────────────────┐ │ Crypto Module │
|
|
│ Decision │◀─────────────────│ (Age keys) │
|
|
│ Publisher │ encrypt() └─────────────────┘
|
|
└─────────────────┘ │
|
|
│ ▼
|
|
│ store() ┌─────────────────┐
|
|
▼ │ Encrypted │
|
|
┌─────────────────┐ announce() │ Content Blob │
|
|
│ DHT Storage │─────────────────▶└─────────────────┘
|
|
│ (with caching) │ │
|
|
└─────────────────┘ ▼
|
|
│ ┌─────────────────┐
|
|
▼ success │ P2P Network │
|
|
┌─────────────────┐ │ (peer notify) │
|
|
│ HTTP Response │ └─────────────────┘
|
|
│ (UCXL address) │
|
|
└─────────────────┘
|
|
```
|
|
|
|
### Module Dependencies
|
|
|
|
```
|
|
Dependency Graph:
|
|
================
|
|
|
|
main.go
|
|
├── api/
|
|
│ ├── handlers.go (depends on all pkg/ modules)
|
|
│ └── server.go (depends on handlers)
|
|
│
|
|
└── pkg/
|
|
├── config/ (no dependencies)
|
|
│ ├── config.go
|
|
│ ├── roles.go
|
|
│ └── validation.go
|
|
│
|
|
├── crypto/ (depends on config/)
|
|
│ ├── age_crypto.go
|
|
│ └── shamir.go
|
|
│
|
|
├── dht/ (depends on crypto/, config/)
|
|
│ └── encrypted_storage.go
|
|
│
|
|
├── ucxl/ (depends on crypto/, dht/, config/)
|
|
│ ├── address.go
|
|
│ └── decision_publisher.go
|
|
│
|
|
├── election/ (depends on crypto/, config/)
|
|
│ └── election.go
|
|
│
|
|
└── ucxi/ (depends on dht/, ucxl/)
|
|
├── server.go
|
|
└── storage.go
|
|
```
|
|
|
|
## Data Flow Diagrams
|
|
|
|
### Decision Publishing Data Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ DECISION PUBLISHING FLOW │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
User/Agent API Layer Service Layer Storage Layer
|
|
│ │ │ │
|
|
│ POST /api/decisions/ │ │ │
|
|
│ architectural │ │ │
|
|
├───────────────────────▶│ │ │
|
|
│ │ │ │
|
|
│ │ 1. Validate │ │
|
|
│ │ request │ │
|
|
│ ├─────────────────────▶│ │
|
|
│ │ │ │
|
|
│ │ │ 2. Generate │
|
|
│ │ │ UCXL address │
|
|
│ │ ├──────────────┐ │
|
|
│ │ │ │ │
|
|
│ │ │◀─────────────┘ │
|
|
│ │ │ │
|
|
│ │ │ 3. Get role keys │
|
|
│ │ │ for encryption │
|
|
│ │ ├──────────────┐ │
|
|
│ │ │ │ │
|
|
│ │ │◀─────────────┘ │
|
|
│ │ │ │
|
|
│ │ │ 4. Encrypt content │
|
|
│ │ │ with Age │
|
|
│ │ ├──────────────┐ │
|
|
│ │ │ │ │
|
|
│ │ │◀─────────────┘ │
|
|
│ │ │ │
|
|
│ │ │ 5. Store encrypted │
|
|
│ │ │ in DHT │
|
|
│ │ ├──────────────────────▶│
|
|
│ │ │ │
|
|
│ │ │ │ 6. Replicate
|
|
│ │ │ │ to peers
|
|
│ │ │ ├─────────┐
|
|
│ │ │ │ │
|
|
│ │ │ │◀────────┘
|
|
│ │ │ │
|
|
│ │ │◀──────────────────────│ 7. Confirm
|
|
│ │ │ │ storage
|
|
│ │ │ │
|
|
│ │◀─────────────────────│ 8. Return success │
|
|
│ │ │ │
|
|
│◀───────────────────────│ 9. HTTP 201 with │ │
|
|
│ │ UCXL address │ │
|
|
│ │ │ │
|
|
```
|
|
|
|
### Content Retrieval Data Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ CONTENT RETRIEVAL FLOW │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Client API Layer Service Layer Storage Layer
|
|
│ │ │ │
|
|
│ GET /api/decisions/ │ │ │
|
|
│ content/{address} │ │ │
|
|
├───────────────────────▶│ │ │
|
|
│ │ │ │
|
|
│ │ 1. Parse UCXL │ │
|
|
│ │ address │ │
|
|
│ ├─────────────────────▶│ │
|
|
│ │ │ │
|
|
│ │ │ 2. Check cache │
|
|
│ │ │ first │
|
|
│ │ ├──────────────────────▶│
|
|
│ │ │ │
|
|
│ │ │◀──────────────────────│ Cache miss
|
|
│ │ │ │
|
|
│ │ │ 3. Query DHT │
|
|
│ │ │ for content │
|
|
│ │ ├──────────────────────▶│
|
|
│ │ │ │
|
|
│ │ │ │ 4. Discover
|
|
│ │ │ │ peers with
|
|
│ │ │ │ content
|
|
│ │ │ ├─────────┐
|
|
│ │ │ │ │
|
|
│ │ │ │◀────────┘
|
|
│ │ │ │
|
|
│ │ │◀──────────────────────│ 5. Return
|
|
│ │ │ encrypted content │ content
|
|
│ │ │ │
|
|
│ │ │ 6. Check role │
|
|
│ │ │ permissions │
|
|
│ │ ├──────────────┐ │
|
|
│ │ │ │ │
|
|
│ │ │◀─────────────┘ │
|
|
│ │ │ │
|
|
│ │ │ 7. Decrypt with │
|
|
│ │ │ Age private key │
|
|
│ │ ├──────────────┐ │
|
|
│ │ │ │ │
|
|
│ │ │◀─────────────┘ │
|
|
│ │ │ │
|
|
│ │ │ 8. Update cache │
|
|
│ │ ├──────────────────────▶│
|
|
│ │ │ │
|
|
│ │◀─────────────────────│ 9. Return decrypted │
|
|
│ │ │ decision │
|
|
│◀───────────────────────│ 10. HTTP 200 with │ │
|
|
│ │ JSON response │ │
|
|
│ │ │ │
|
|
```
|
|
|
|
### Election Process Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ ELECTION FLOW │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Admin Timeout Nodes Election Manager Consensus
|
|
│ │ │ │
|
|
│ Heartbeat timeout │ │ │
|
|
│ detected │ │ │
|
|
├───────────────────────▶│ │ │
|
|
│ │ │ │
|
|
│ │ 1. Trigger election │ │
|
|
│ ├──────────────────────────▶│ │
|
|
│ │ │ │
|
|
│ │ │ 2. Collect eligible │
|
|
│ │ │ candidates │
|
|
│ │ ├─────────────┐ │
|
|
│ │ │ │ │
|
|
│ │ │◀────────────┘ │
|
|
│ │ │ │
|
|
│ │ │ 3. Calculate │
|
|
│ │ │ scores │
|
|
│ │ ├─────────────┐ │
|
|
│ │ │ │ │
|
|
│ │ │◀────────────┘ │
|
|
│ │ │ │
|
|
│ │ │ 4. Start consensus │
|
|
│ │ ├─────────────────────▶│
|
|
│ │ │ │
|
|
│ │◀──────────────────────────┼──────────────────────│ 5. Voting
|
|
│ │ Vote request │ │ round
|
|
│ │ │ │
|
|
│ │ Vote response │ │
|
|
│ ├──────────────────────────▶├─────────────────────▶│
|
|
│ │ │ │
|
|
│ │ │◀─────────────────────│ 6. Tally
|
|
│ │ │ votes │ votes
|
|
│ │ │ │
|
|
│ │ │ 7. Determine │
|
|
│ │ │ winner │
|
|
│ │ ├─────────────┐ │
|
|
│ │ │ │ │
|
|
│ │ │◀────────────┘ │
|
|
│ │ │ │
|
|
│ │◀──────────────────────────│ 8. Announce │
|
|
│ │ New admin │ new admin │
|
|
│ │ │ │
|
|
│ │ 9. Distribute admin │ │
|
|
│ │ key shares │ │
|
|
│ ├──────────────────────────▶│ │
|
|
│ │ │ │
|
|
│◀───────────────────────│ 10. Resume operations │ │
|
|
│ New admin heartbeats │ │ │
|
|
│ │ │ │
|
|
```
|
|
|
|
## Network Architecture
|
|
|
|
### P2P Network Topology
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ P2P NETWORK TOPOLOGY │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Internet
|
|
│
|
|
┌───────────┼───────────┐
|
|
│ │ │
|
|
┌─────────┐ ┌─────────┐ ┌─────────┐
|
|
│Bootstrap│ │Bootstrap│ │Bootstrap│
|
|
│ Node A │ │ Node B │ │ Node C │
|
|
└─────────┘ └─────────┘ └─────────┘
|
|
│ │ │
|
|
┌───────┼───────────┼───────────┼───────┐
|
|
│ │ │ │ │
|
|
┌─────────┐ │ ┌─────────┐ │ ┌─────────┐
|
|
│ Region │ │ │ Region │ │ │ Region │
|
|
│ West │ │ │ Central │ │ │ East │
|
|
└─────────┘ │ └─────────┘ │ └─────────┘
|
|
│ │ │ │ │
|
|
│ ┌─────────┐ │ ┌─────────┐ │
|
|
│ │ Node W1 │ │ │ Node E1 │ │
|
|
│ └─────────┘ │ └─────────┘ │
|
|
│ │ │ │ │
|
|
┌─────────┐ │ ┌─────────┐ │ ┌─────────┐
|
|
│ Node W2 │ │ │ Node C1 │ │ │ Node E2 │
|
|
└─────────┘ │ └─────────┘ │ └─────────┘
|
|
│ │ │
|
|
┌─────────┐ │ ┌─────────┐
|
|
│ Node W3 │ │ │ Node E3 │
|
|
└─────────┘ │ └─────────┘
|
|
┌─────────┐
|
|
│ Node C2 │
|
|
└─────────┘
|
|
|
|
Connection Types:
|
|
─────────────────
|
|
━━━━━ Bootstrap connections (always maintained)
|
|
────── Regional connections (high bandwidth)
|
|
┄┄┄┄┄ Cross-region connections (selective)
|
|
```
|
|
|
|
### Network Communication Patterns
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ COMMUNICATION PATTERNS │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
1. Peer Discovery:
|
|
==================
|
|
|
|
New Node Bootstrap Nodes DHT Network
|
|
│ │ │
|
|
│ 1. Connection request │ │
|
|
├───────────────────────▶│ │
|
|
│ │ │
|
|
│◀───────────────────────│ 2. Peer list │
|
|
│ │ │
|
|
│ 3. DHT join request │ │
|
|
├───────────────────────────────────────────────────▶│
|
|
│ │ │
|
|
│◀───────────────────────────────────────────────────│ 4. Routing table
|
|
│ │ │
|
|
│ 5. Announce services │ │
|
|
├───────────────────────▶├─────────────────────────▶│
|
|
│ │ │
|
|
|
|
2. Content Distribution:
|
|
========================
|
|
|
|
Publisher DHT Nodes Subscribers
|
|
│ │ │
|
|
│ 1. Store content │ │
|
|
├──────────────────────▶│ │
|
|
│ │ │
|
|
│ │ 2. Replicate to peers │
|
|
│ ├─────────────┐ │
|
|
│ │ │ │
|
|
│ │◀────────────┘ │
|
|
│ │ │
|
|
│ │ 3. Announce availability │
|
|
│ ├──────────────────────────▶│
|
|
│ │ │
|
|
│◀───────────────────────│ 4. Confirm storage │
|
|
│ │ │
|
|
|
|
3. Event Broadcasting:
|
|
======================
|
|
|
|
Event Source PubSub Network Subscribers
|
|
│ │ │
|
|
│ 1. Publish event │ │
|
|
├──────────────────────▶│ │
|
|
│ │ │
|
|
│ │ 2. Flood to subscribers │
|
|
│ ├──────────────────────────▶│
|
|
│ │ │
|
|
│ │ 3. Delivery confirmation │
|
|
│ │◀──────────────────────────│
|
|
│ │ │
|
|
│◀───────────────────────│ 4. Ack aggregation │
|
|
│ │ │
|
|
```
|
|
|
|
## Security Architecture
|
|
|
|
### Security Layers
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ SECURITY ARCHITECTURE │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Application Security:
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ Input │ │ RBAC │ │ Session │ │ Audit │ │
|
|
│ │ Validation │ │ Authority │ │ Management │ │ Logging │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
Cryptographic Security:
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ Age │ │ Shamir │ │ Key │ │ Digital │ │
|
|
│ │ Encryption │ │ Secret │ │ Management │ │ Signatures │ │
|
|
│ │ │ │ Sharing │ │ │ │ │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
Network Security:
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ TLS 1.3 │ │ Peer │ │ Rate │ │ DDoS │ │
|
|
│ │ Transport │ │ Identity │ │ Limiting │ │ Protection │ │
|
|
│ │ Encryption │ │Verification │ │ │ │ │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
Infrastructure Security:
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ Container │ │ Resource │ │ Network │ │ Monitoring │ │
|
|
│ │ Security │ │ Isolation │ │ Policies │ │ & Alerting │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Access Control Matrix
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ ROLE-BASED ACCESS CONTROL │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Operations vs Roles Matrix:
|
|
============================
|
|
|
|
│ Obs │ Back│ Arch│Admin│
|
|
Operation │ erver│ Dev │ itect│ │
|
|
─────────────────────────────┼─────┼─────┼─────┼─────┤
|
|
Read Decisions (own role) │ ✓ │ ✓ │ ✓ │ ✓ │
|
|
Read Decisions (other roles) │ ✗ │ P │ ✓ │ ✓ │
|
|
Publish Suggestions │ ✓ │ ✓ │ ✓ │ ✓ │
|
|
Publish Decisions │ ✗ │ ✓ │ ✓ │ ✓ │
|
|
Publish Architectural │ ✗ │ ✗ │ ✓ │ ✓ │
|
|
Trigger Elections │ ✗ │ ✗ │ ✗ │ ✓ │
|
|
Key Management │ ✗ │ ✗ │ ✗ │ ✓ │
|
|
System Configuration │ ✗ │ ✗ │ P │ ✓ │
|
|
Debug Access │ ✗ │ P │ ✓ │ ✓ │
|
|
Raw DHT Access │ ✗ │ ✗ │ ✗ │ ✓ │
|
|
|
|
Legend: ✓ = Allowed, ✗ = Denied, P = Partial/Conditional
|
|
|
|
Encryption Hierarchy:
|
|
=====================
|
|
|
|
Admin (master authority)
|
|
│
|
|
├─ Can decrypt ALL content
|
|
│
|
|
├─ Senior Software Architect (decision authority)
|
|
│ │
|
|
│ ├─ Can decrypt: architect, backend_dev, observer
|
|
│ │
|
|
│ └─ Backend Developer (suggestion authority)
|
|
│ │
|
|
│ ├─ Can decrypt: backend_dev, observer
|
|
│ │
|
|
│ └─ Observer (read_only authority)
|
|
│ │
|
|
│ └─ Can decrypt: observer only
|
|
```
|
|
|
|
### Key Management Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ KEY MANAGEMENT │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Admin Key Lifecycle:
|
|
====================
|
|
|
|
Key Generation Key Distribution Key Recovery
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────┐ ┌─────────────┐ ┌──────────┐
|
|
│Generate │ │ Shamir │ │Consensus │
|
|
│ Age │ │ Split into │ │ Gather │
|
|
│KeyPair │ │ 5 shares │ │3+ shares │
|
|
└─────────┘ │(threshold 3)│ └──────────┘
|
|
│ └─────────────┘ │
|
|
▼ │ ▼
|
|
┌─────────┐ ▼ ┌──────────┐
|
|
│ Master │ ┌─────────────┐ │Reconstruct│
|
|
│ Private │ │Distribute │ │ Master │
|
|
│ Key │ │shares to │ │ Key │
|
|
└─────────┘ │ 5 nodes │ └──────────┘
|
|
│ └─────────────┘ │
|
|
│ ▼
|
|
└──────────────────────────────────────────────┘
|
|
Key Rotation (every 30 days)
|
|
|
|
Role Key Management:
|
|
====================
|
|
|
|
Role Definition Key Assignment Key Usage
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────┐ ┌─────────────┐ ┌──────────┐
|
|
│Configure│ │ Generate │ │ Encrypt │
|
|
│ Role │ │ Age keypair │ │ for │
|
|
│Authority│ │ for role │ │ multiple │
|
|
│ & Scope │ └─────────────┘ │recipients│
|
|
└─────────┘ │ └──────────┘
|
|
│ ▼ │
|
|
▼ ┌─────────────┐ ▼
|
|
┌─────────┐ │ Store keys │ ┌──────────┐
|
|
│Hierarchy│ │ in secure │ │ Decrypt │
|
|
│ Rules │ │ config │ │with role │
|
|
│ (inherit│ └─────────────┘ │ private │
|
|
│ from) │ │ │ key │
|
|
└─────────┘ │ └──────────┘
|
|
▼
|
|
┌─────────────┐
|
|
│ Automatic │
|
|
│ rotation │
|
|
│ (90 days) │
|
|
└─────────────┘
|
|
```
|
|
|
|
## Deployment Architecture
|
|
|
|
### Container Orchestration
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ DOCKER SWARM DEPLOYMENT │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Manager Nodes: Worker Nodes:
|
|
============= =============
|
|
|
|
┌─────────────┐ ┌─────────────┐
|
|
│ Manager │ │ Worker │
|
|
│ Node │ ──── Raft ────────────│ Node │
|
|
│ #1 │ Consensus │ #1 │
|
|
│ │ │ │
|
|
│ • Leader │ │ • BZZZ │
|
|
│ • Scheduler │ │ Services │
|
|
│ • API │ │ • Load Bal │
|
|
└─────────────┘ └─────────────┘
|
|
│ │
|
|
│ │
|
|
┌─────────────┐ ┌─────────────┐
|
|
│ Manager │ │ Worker │
|
|
│ Node │ │ Node │
|
|
│ #2 │ │ #2 │
|
|
│ │ │ │
|
|
│ • Follower │ │ • BZZZ │
|
|
│ • Standby │ │ Services │
|
|
└─────────────┘ │ • Monitoring│
|
|
│ └─────────────┘
|
|
│ │
|
|
┌─────────────┐ ┌─────────────┐
|
|
│ Manager │ │ Worker │
|
|
│ Node │ │ Node │
|
|
│ #3 │ │ #3 │
|
|
│ │ │ │
|
|
│ • Follower │ │ • BZZZ │
|
|
│ • Standby │ │ Services │
|
|
└─────────────┘ │ • Storage │
|
|
└─────────────┘
|
|
|
|
Service Distribution:
|
|
=====================
|
|
|
|
BZZZ Application Stack:
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ BZZZ │ │ BZZZ │ │ BZZZ │ │
|
|
│ │ Node 1 │ │ Node 2 │ │ Node 3 │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ Port:8080│ │ Port:8080│ │ Port:8080│ │
|
|
│ └──────────┘ └──────────┘ └──────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────┘
|
|
|
|
Load Balancer:
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ ┌──────────┐ ┌──────────┐ │
|
|
│ │ HAProxy │ Ingress │ Traefik │ │
|
|
│ │ LB │ ◀──────────▶│ Reverse │ │
|
|
│ │ │ │ Proxy │ │
|
|
│ └──────────┘ └──────────┘ │
|
|
└─────────────────────────────────────────────────────┘
|
|
|
|
Monitoring Stack:
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │Prometheus│ │ Grafana │ │AlertMgr │ │
|
|
│ │ Metrics │ │Dashboard │ │Alerting │ │
|
|
│ └──────────┘ └──────────┘ └──────────┘ │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### High Availability Configuration
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ HIGH AVAILABILITY SETUP │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Multi-Zone Deployment:
|
|
======================
|
|
|
|
Zone A Zone B Zone C
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
│ Manager │ │ Manager │ │ Manager │
|
|
│ + Worker │ │ + Worker │ │ + Worker │
|
|
│ │ │ │ │ │
|
|
│ • BZZZ Node │ │ • BZZZ Node │ │ • BZZZ Node │
|
|
│ • Storage │ │ • Storage │ │ • Storage │
|
|
│ • Monitor │ │ • Monitor │ │ • Monitor │
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
│ │ │
|
|
└──────────────────┼──────────────────┘
|
|
│
|
|
Cross-Zone Network
|
|
(Encrypted Overlay)
|
|
|
|
Failure Scenarios:
|
|
==================
|
|
|
|
1. Node Failure:
|
|
┌─────────┐ ┌─────────┐ ┌─────────┐
|
|
│ Node A │ │ Node B │ │ Node C │
|
|
│ ❌ │ │ ✅ │ │ ✅ │
|
|
└─────────┘ └─────────┘ └─────────┘
|
|
Result: Automatic failover, services migrate to B & C
|
|
|
|
2. Zone Failure:
|
|
┌─────────┐ ┌─────────┐ ┌─────────┐
|
|
│ Zone A │ │ Zone B │ │ Zone C │
|
|
│ ❌ │ │ ✅ │ │ ✅ │
|
|
└─────────┘ └─────────┘ └─────────┘
|
|
Result: Cluster continues with 2/3 zones
|
|
|
|
3. Network Partition:
|
|
┌─────────┐ ┌─────────┐ ╲╱ ┌─────────┐
|
|
│ Zone A │ │ Zone B │ ╱╲ │ Zone C │
|
|
│ ✅ │ │ ✅ │ │ ❌ │
|
|
└─────────┘ └─────────┘ └─────────┘
|
|
Result: Majority partition (A+B) continues operation
|
|
```
|
|
|
|
### Scaling Patterns
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ SCALING PATTERNS │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Horizontal Scaling:
|
|
==================
|
|
|
|
Load Increase:
|
|
┌─────────────┐
|
|
│ 3 Nodes │ ──▶ CPU > 70% for 5 minutes
|
|
│ Normal │ Memory > 80% for 5 minutes
|
|
└─────────────┘
|
|
│
|
|
▼ Trigger Scale-Out
|
|
┌─────────────┐
|
|
│ 6 Nodes │ ──▶ Add 3 additional nodes
|
|
│ High Load │ Redistribute services
|
|
└─────────────┘
|
|
│
|
|
▼ Load Decreased
|
|
┌─────────────┐
|
|
│ 4 Nodes │ ──▶ Scale down to 4 nodes
|
|
│ Optimized │ (keep minimum for HA)
|
|
└─────────────┘
|
|
|
|
Vertical Scaling:
|
|
=================
|
|
|
|
Resource Optimization:
|
|
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
|
|
│ Small Nodes │ ───▶ │ Medium Nodes │ ───▶ │ Large Nodes │
|
|
│ │ │ │ │ │
|
|
│ 2 CPU cores │ │ 4 CPU cores │ │ 8 CPU cores │
|
|
│ 4 GB RAM │ │ 8 GB RAM │ │ 16 GB RAM │
|
|
│ 50 GB storage │ │ 100 GB storage │ │ 200 GB storage │
|
|
└────────────────┘ └────────────────┘ └────────────────┘
|
|
|
|
Load Balancing Strategy:
|
|
========================
|
|
|
|
Internet Traffic
|
|
│
|
|
▼
|
|
┌─────────────────────┐
|
|
│ Load Balancer │
|
|
│ (HAProxy/Traefik) │
|
|
└─────────────────────┘
|
|
│
|
|
┌────────────┼────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
│ BZZZ Node 1 │ │ BZZZ Node 2 │ │ BZZZ Node 3 │
|
|
│ Weight: 1 │ │ Weight: 1 │ │ Weight: 1 │
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
│ │ │
|
|
└────────────┼────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────┐
|
|
│ Shared Storage │
|
|
│ (DHT Network) │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
## Integration Patterns
|
|
|
|
### Microservices Integration
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ MICROSERVICES INTEGRATION │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Service Mesh Integration:
|
|
=========================
|
|
|
|
┌─────────────────────────────────────────┐
|
|
│ Service Mesh │
|
|
│ (Istio/Envoy) │
|
|
└─────────────────────────────────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
│ User │ │ Order │ │ Inventory │
|
|
│ Service │ │ Service │ │ Service │
|
|
│ │ │ │ │ │
|
|
│ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │
|
|
│ │ BZZZ │ │ │ │ BZZZ │ │ │ │ BZZZ │ │
|
|
│ │ Client │ │ │ │ Client │ │ │ │ Client │ │
|
|
│ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
│ │ │
|
|
└──────────────┼──────────────┘
|
|
▼
|
|
┌─────────────────┐
|
|
│ BZZZ Cluster │
|
|
│ (Shared State) │
|
|
└─────────────────┘
|
|
|
|
Event-Driven Architecture:
|
|
==========================
|
|
|
|
Event Source Event Bus Event Consumers
|
|
│ │ │
|
|
│ 1. Business Event │ │
|
|
├──────────────────────▶│ │
|
|
│ │ │
|
|
│ │ 2. Route to BZZZ │
|
|
│ ├────────────────────────▶│
|
|
│ │ │
|
|
│ │ 3. Publish Decision │
|
|
│ │◀────────────────────────┤
|
|
│ │ │
|
|
│ │ 4. Decision Event │
|
|
│ ├────────────────────────▶│
|
|
│ │ │
|
|
│◀───────────────────────│ 5. Event Confirmation │
|
|
│ │ │
|
|
|
|
API Gateway Integration:
|
|
========================
|
|
|
|
Client Apps API Gateway Backend Services
|
|
│ │ │
|
|
│ 1. Request with Auth │ │
|
|
├──────────────────────▶│ │
|
|
│ │ │
|
|
│ │ 2. Route to Service │
|
|
│ ├────────────────────────▶│
|
|
│ │ │
|
|
│ │ 3. BZZZ Decision Pub │
|
|
│ │◀────────────────────────┤
|
|
│ │ │
|
|
│◀───────────────────────│ 4. Response + Metadata │
|
|
│ │ │
|
|
```
|
|
|
|
### CI/CD Integration
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ CI/CD INTEGRATION │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
Development Workflow:
|
|
=====================
|
|
|
|
Developer CI/CD Pipeline BZZZ System
|
|
│ │ │
|
|
│ 1. Code commit │ │
|
|
├──────────────────────────▶│ │
|
|
│ │ │
|
|
│ │ 2. Run tests │
|
|
│ ├────────────┐ │
|
|
│ │ │ │
|
|
│ │◀───────────┘ │
|
|
│ │ │
|
|
│ │ 3. Build & Deploy │
|
|
│ ├────────────┐ │
|
|
│ │ │ │
|
|
│ │◀───────────┘ │
|
|
│ │ │
|
|
│ │ 4. Publish Decision │
|
|
│ ├───────────────────────────▶│
|
|
│ │ │
|
|
│◀──────────────────────────┼────────────────────────────│ 5. Decision Event
|
|
│ │ │
|
|
|
|
Pipeline Configuration:
|
|
=======================
|
|
|
|
# .github/workflows/bzzz-integration.yml
|
|
name: BZZZ Integration
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
pull_request:
|
|
branches: [main]
|
|
|
|
jobs:
|
|
build-and-notify:
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v3
|
|
|
|
- name: Run Tests
|
|
run: |
|
|
go test ./...
|
|
|
|
- name: Build Application
|
|
run: |
|
|
go build -o app ./cmd/main.go
|
|
|
|
- name: Publish to BZZZ
|
|
env:
|
|
BZZZ_ENDPOINT: ${{ secrets.BZZZ_ENDPOINT }}
|
|
BZZZ_ROLE: backend_developer
|
|
run: |
|
|
curl -X POST "${BZZZ_ENDPOINT}/api/decisions/code" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"task": "ci_build_${{ github.run_id }}",
|
|
"decision": "Automated build completed",
|
|
"files_modified": ["${{ github.event.head_commit.modified }}"],
|
|
"test_results": {
|
|
"passed": ${{ env.TEST_PASSED }},
|
|
"failed": ${{ env.TEST_FAILED }}
|
|
},
|
|
"success": true
|
|
}'
|
|
|
|
Deployment Tracking:
|
|
====================
|
|
|
|
Deployment Stage BZZZ Decision Monitoring
|
|
│ │ │
|
|
│ 1. Pre-deploy │ │
|
|
├──────────────────────▶│ │
|
|
│ │ │
|
|
│ 2. Deploy to staging │ │
|
|
├──────────────────────▶│ │
|
|
│ │ │
|
|
│ │ 3. Health check │
|
|
│ ├───────────────────────▶│
|
|
│ │ │
|
|
│ │◀───────────────────────│ 4. Status report
|
|
│ │ │
|
|
│ 5. Deploy to prod │ │
|
|
├──────────────────────▶│ │
|
|
│ │ │
|
|
│ 6. Post-deploy │ │
|
|
├──────────────────────▶│ │
|
|
│ │ │
|
|
```
|
|
|
|
---
|
|
|
|
## Cross-References
|
|
|
|
- **Technical Report**: [TECHNICAL_REPORT.md](TECHNICAL_REPORT.md)
|
|
- **User Manual**: [USER_MANUAL.md](USER_MANUAL.md)
|
|
- **Developer Guide**: [DEVELOPER.md](DEVELOPER.md)
|
|
- **API Reference**: [API_REFERENCE.md](API_REFERENCE.md)
|
|
- **SDK Documentation**: [BZZZv2B-SDK.md](BZZZv2B-SDK.md)
|
|
|
|
**BZZZ Architecture Documentation v2.0** - Comprehensive architectural analysis with detailed system diagrams for Phase 2B unified architecture. |