# 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.