bzzz/docs/BZZZv2B-DEVELOPER.md

BZZZ Developer Guide

Version 2.0 - Phase 2B Edition
Complete developer documentation for contributing to and extending BZZZ.

Table of Contents

1. Development Environment
2. Architecture Deep Dive
3. Code Organization
4. Building & Testing
5. Extending BZZZ
6. Debugging & Profiling
7. Contributing Guidelines
8. Advanced Topics

Development Environment

Prerequisites

Required:

• Go 1.23+ (for Go modules and generics support)
• Git (for version control)
• Make (for build automation)

Optional but Recommended:

• Docker & Docker Compose (for integration testing)
• golangci-lint (for code quality)
• delve (for debugging)

Environment Setup

1. Clone Repository:

git clone https://github.com/anthonyrawlins/bzzz.git
cd bzzz

2. Install Dependencies:

go mod download
go mod verify

3. Install Development Tools:

# Install linter
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.54.2

# Install debugger
go install github.com/go-delve/delve/cmd/dlv@latest

# Install test coverage tools
go install golang.org/x/tools/cmd/cover@latest

4. Verify Installation:

make test
make lint

IDE Configuration

VS Code Settings

Create .vscode/settings.json:

{
  "go.lintTool": "golangci-lint",
  "go.lintFlags": [
    "--fast"
  ],
  "go.testFlags": ["-v"],
  "go.testTimeout": "60s",
  "go.coverageOptions": "showUncoveredCodeOnly",
  "go.toolsManagement.checkForUpdates": "local"
}

GoLand Configuration

• Enable Go modules support
• Configure golangci-lint as external tool
• Set up run configurations for different components

Cross-Reference: Development setup in docs/CONTRIBUTING.md

Architecture Deep Dive

System Components

BZZZ Phase 2B consists of several interconnected components:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Main App      │────│  Election Mgr   │────│  Admin Roles    │
│   (main.go)     │    │  (election/)    │    │  (config/)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   P2P Network   │────│   DHT Storage   │────│  Age Crypto     │
│   (p2p/)        │    │   (dht/)        │    │  (crypto/)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   PubSub        │────│  Decision Pub   │────│  UCXL Protocol  │
│   (pubsub/)     │    │  (ucxl/)        │    │  (ucxi/)        │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Data Flow Architecture

Decision Publishing Flow

Task Completion → Decision Publisher → Age Encryption → DHT Storage
      ↓                    ↓                 ↓              ↓
Task Tracker     →    UCXL Address   →   Role Keys    →   P2P DHT
      ↓                    ↓                 ↓              ↓  
Metadata Gen     →    Content Format →   Multi-Recip  →   Cache + Announce

Implementation Files:

• main.go:CompleteTaskWithDecision() - Task completion trigger
• pkg/ucxl/decision_publisher.go - Decision publishing logic
• pkg/crypto/age_crypto.go - Encryption implementation
• pkg/dht/encrypted_storage.go - DHT storage with encryption

Election & Admin Flow

Heartbeat Timeout → Election Trigger → Consensus Vote → Admin Selection
       ↓                   ↓               ↓              ↓
Monitor Admin    →    Candidate List →  Raft Protocol →  Key Reconstruction
       ↓                   ↓               ↓              ↓
Health Checks    →    Score Calculation → Share Collection → SLURP Enable

Implementation Files:

• pkg/election/election.go - Complete election system
• pkg/crypto/shamir.go - Key reconstruction
• pkg/config/roles.go - Role and authority management

Security Architecture

Role-Based Access Control

Content Creation → Authority Check → Key Selection → Multi-Recipient Encryption
       ↓                ↓              ↓                    ↓
Role Definition → Authority Level → Age Key Pairs → Encrypted Content
       ↓                ↓              ↓                    ↓
Config System   → Hierarchy Rules → Crypto Module → DHT Storage

Key Management System

Admin Key → Shamir Split → Distribute Shares → Consensus → Reconstruction
    ↓           ↓              ↓               ↓           ↓
Master Key → 5 Shares    → Node Storage   → Election  → Admin Access
    ↓           ↓              ↓               ↓           ↓
Age Identity → Threshold 3 → Secure Store → Validate → Enable SLURP

Cross-Reference: Security model details in docs/SECURITY.md

Code Organization

Package Structure

bzzz/
├── main.go                    # Application entry point
├── go.mod                     # Go module definition
├── go.sum                     # Dependency checksums
├── Makefile                   # Build automation
│
├── api/                       # HTTP API handlers
│   ├── handlers.go           # Request handlers
│   ├── middleware.go         # Authentication, logging
│   └── server.go             # HTTP server setup
│
├── pkg/                       # Core packages
│   ├── config/               # Configuration management
│   │   ├── config.go         # Main configuration
│   │   ├── roles.go          # Role definitions
│   │   └── defaults.go       # Default values
│   │
│   ├── crypto/               # Cryptographic operations
│   │   ├── age_crypto.go     # Age encryption
│   │   └── shamir.go         # Secret sharing
│   │
│   ├── dht/                  # DHT storage
│   │   └── encrypted_storage.go # Encrypted DHT operations
│   │
│   ├── election/             # Admin elections
│   │   └── election.go       # Election management
│   │
│   ├── ucxl/                 # UCXL protocol
│   │   ├── address.go        # Address parsing
│   │   └── decision_publisher.go # Decision publishing
│   │
│   └── ucxi/                 # UCXI interface
│       ├── server.go         # UCXI REST server
│       └── storage.go        # Content storage
│
├── docs/                     # Documentation
│   ├── README.md            # Documentation index
│   ├── USER_MANUAL.md       # User guide
│   ├── API_REFERENCE.md     # API documentation
│   └── DEVELOPER.md         # This file
│
└── tests/                    # Test files
    ├── integration/          # Integration tests
    ├── unit/                # Unit tests
    └── fixtures/            # Test data

Coding Standards

Go Style Guidelines

Package Naming:

• Use short, lowercase names
• Avoid underscores or mixed caps
• Be descriptive but concise

// Good
package crypto
package election

// Avoid
package cryptoOperations
package election_management

Function Documentation:

// EncryptForRole encrypts content for a specific role using Age encryption.
//
// This function encrypts the provided content using the Age public key
// associated with the specified role. The encrypted content can only be
// decrypted by agents with the corresponding private key and appropriate
// authority level.
//
// Parameters:
//   content: Raw content bytes to encrypt
//   roleName: Target role name for encryption
//
// Returns:
//   []byte: Encrypted content in Age format
//   error: Any error during encryption process
//
// Cross-references:
//   - DecryptWithRole(): Corresponding decryption function
//   - pkg/config/roles.go: Role definitions and key management
//   - docs/SECURITY.md: Security model and threat analysis
func (ac *AgeCrypto) EncryptForRole(content []byte, roleName string) ([]byte, error) {
    // Implementation...
}

Error Handling:

// Good - Wrap errors with context
if err != nil {
    return fmt.Errorf("failed to encrypt content for role %s: %w", roleName, err)
}

// Good - Use custom error types for specific cases
type InvalidRoleError struct {
    Role string
}

func (e InvalidRoleError) Error() string {
    return fmt.Sprintf("invalid role: %s", e.Role)
}

Configuration Management

All configuration uses the centralized config system:

// Reading configuration
cfg, err := config.LoadConfig("config.yaml")
if err != nil {
    return fmt.Errorf("failed to load config: %w", err)
}

// Accessing role information
role, exists := config.GetPredefinedRoles()[cfg.Agent.Role]
if !exists {
    return fmt.Errorf("role %s not found", cfg.Agent.Role)
}

// Checking permissions
canDecrypt, err := cfg.CanDecryptRole(targetRole)
if err != nil {
    return fmt.Errorf("permission check failed: %w", err)
}

Cross-Reference: Configuration system in pkg/config/config.go

Testing Conventions

Unit Tests

func TestAgeCrypto_EncryptForRole(t *testing.T) {
    tests := []struct {
        name         string
        content      []byte
        roleName     string
        wantErr      bool
        errorContains string
    }{
        {
            name:     "successful encryption",
            content:  []byte("test content"),
            roleName: "backend_developer",
            wantErr:  false,
        },
        {
            name:         "invalid role",
            content:      []byte("test content"),
            roleName:     "nonexistent_role", 
            wantErr:      true,
            errorContains: "role 'nonexistent_role' not found",
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // Test implementation
            cfg := &config.Config{/* test config */}
            ac := NewAgeCrypto(cfg)
            
            encrypted, err := ac.EncryptForRole(tt.content, tt.roleName)
            
            if tt.wantErr {
                require.Error(t, err)
                if tt.errorContains != "" {
                    assert.Contains(t, err.Error(), tt.errorContains)
                }
                return
            }
            
            require.NoError(t, err)
            assert.NotEmpty(t, encrypted)
            assert.NotEqual(t, tt.content, encrypted)
        })
    }
}

Integration Tests

func TestEndToEndDecisionFlow(t *testing.T) {
    // Set up test cluster
    cluster := setupTestCluster(t, 3)
    defer cluster.Shutdown()
    
    // Test decision publishing
    decision := &ucxl.TaskDecision{
        Task:     "test_task",
        Decision: "test decision content",
        Success:  true,
    }
    
    err := cluster.PublishDecision("backend_developer", decision)
    require.NoError(t, err)
    
    // Test content retrieval
    retrieved, err := cluster.RetrieveDecision(decision.UCXLAddress())
    require.NoError(t, err)
    
    assert.Equal(t, decision.Decision, retrieved.Decision)
}

Cross-Reference: Test examples in tests/ directory

Building & Testing

Build System

Makefile Targets

# Build binary
build:
	go build -o bin/bzzz main.go

# Run tests
test:
	go test -v ./...

# Run tests with coverage
test-coverage:
	go test -v -coverprofile=coverage.out ./...
	go tool cover -html=coverage.out -o coverage.html

# Lint code
lint:
	golangci-lint run

# Format code
fmt:
	go fmt ./...
	goimports -w .

# Clean build artifacts
clean:
	rm -rf bin/ coverage.out coverage.html

# Development server with hot reload
dev:
	air -c .air.toml

# Integration tests
test-integration:
	go test -v -tags=integration ./tests/integration/

# Generate documentation
docs:
	go doc -all ./... > docs/GENERATED_API_DOCS.md

Build Configuration

// Build with version information
go build -ldflags "-X main.version=$(git describe --tags) -X main.commit=$(git rev-parse --short HEAD)" -o bzzz main.go

Testing Strategy

Test Categories

1. Unit Tests (*_test.go files)

   • Individual function testing
   • Mock external dependencies
   • Fast execution (< 1s per test)

2. Integration Tests (tests/integration/)

   • Component interaction testing
   • Real dependencies where possible
   • Moderate execution time (< 30s per test)

3. End-to-End Tests (tests/e2e/)

   • Full system testing
   • Multiple nodes, real network
   • Longer execution time (< 5min per test)

Running Tests

# All tests
make test

# Specific package
go test -v ./pkg/crypto/

# Specific test
go test -v ./pkg/crypto/ -run TestAgeCrypto_EncryptForRole

# With race detection
go test -race ./...

# With coverage
make test-coverage

# Integration tests only
make test-integration

# Benchmark tests
go test -bench=. ./pkg/crypto/

Test Data Management

// Use testdata directory for test fixtures
func loadTestConfig(t *testing.T) *config.Config {
    configPath := filepath.Join("testdata", "test_config.yaml")
    cfg, err := config.LoadConfig(configPath)
    require.NoError(t, err)
    return cfg
}

// Generate test data deterministically
func generateTestKeys(t *testing.T) *config.AgeKeyPair {
    // Use fixed seed for reproducible tests
    oldRand := rand.Reader
    defer func() { rand.Reader = oldRand }()
    
    seed := make([]byte, 32)
    copy(seed, "test-seed-for-deterministic-keys")
    rand.Reader = bytes.NewReader(seed)
    
    keyPair, err := crypto.GenerateAgeKeyPair()
    require.NoError(t, err)
    return keyPair
}

Extending BZZZ

Adding New Decision Types

1. Define Decision Structure:

// pkg/ucxl/decision_types.go
type CustomDecision struct {
    TaskDecision                    // Embed base decision
    CustomField1 string            `json:"custom_field_1"`
    CustomField2 map[string]int    `json:"custom_field_2"`
    CustomField3 []CustomSubType   `json:"custom_field_3"`
}

type CustomSubType struct {
    Name  string `json:"name"`
    Value int    `json:"value"`
}

2. Add Publisher Method:

// pkg/ucxl/decision_publisher.go
func (dp *DecisionPublisher) PublishCustomDecision(
    taskName string,
    customField1 string,
    customField2 map[string]int,
    customField3 []CustomSubType,
) error {
    decision := &CustomDecision{
        TaskDecision: TaskDecision{
            Task:     taskName,
            Decision: "Custom decision type",
            Success:  true,
            Context: map[string]interface{}{
                "decision_type": "custom",
                "node_id":       dp.nodeID,
            },
        },
        CustomField1: customField1,
        CustomField2: customField2,
        CustomField3: customField3,
    }
    
    return dp.PublishTaskDecision(&decision.TaskDecision)
}

3. Add API Endpoint:

// api/handlers.go
func (h *Handlers) HandleCustomDecision(w http.ResponseWriter, r *http.Request) {
    var req struct {
        Task         string              `json:"task"`
        CustomField1 string              `json:"custom_field_1"`
        CustomField2 map[string]int      `json:"custom_field_2"`
        CustomField3 []CustomSubType     `json:"custom_field_3"`
    }
    
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, "Invalid request body", http.StatusBadRequest)
        return
    }
    
    err := h.decisionPublisher.PublishCustomDecision(
        req.Task,
        req.CustomField1, 
        req.CustomField2,
        req.CustomField3,
    )
    
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    
    w.WriteHeader(http.StatusCreated)
    json.NewEncoder(w).Encode(map[string]string{
        "status": "published",
        "type":   "custom",
    })
}

4. Register Route:

// api/server.go
func (s *HTTPServer) setupRoutes() {
    // ... existing routes
    s.router.HandleFunc("/api/decisions/custom", s.handlers.HandleCustomDecision).Methods("POST")
}

Adding New Role Types

1. Define Role in Configuration:

# .ucxl/roles.yaml
data_scientist:
  authority_level: decision
  can_decrypt: [data_scientist, backend_developer, observer]
  model: ollama/llama3.1
  decision_scope: [data, analytics, ml_models]
  special_functions: [data_analysis, model_training]
  age_keys:
    public_key: "age1..."
    private_key: "AGE-SECRET-KEY-1..."

2. Add Role Logic:

// pkg/config/roles.go
func GetDataScienceDefaults() RoleDefinition {
    return RoleDefinition{
        AuthorityLevel:    AuthorityDecision,
        CanDecrypt:       []string{"data_scientist", "backend_developer", "observer"},
        Model:            "ollama/llama3.1",
        DecisionScope:    []string{"data", "analytics", "ml_models"},
        SpecialFunctions: []string{"data_analysis", "model_training"},
        AgeKeys:          AgeKeyPair{}, // Will be populated at runtime
    }
}

// Add to role factory
func GetPredefinedRoles() map[string]RoleDefinition {
    return map[string]RoleDefinition{
        // ... existing roles
        "data_scientist": GetDataScienceDefaults(),
    }
}

3. Add Specialized Methods:

// pkg/ucxl/data_science_publisher.go
func (dp *DecisionPublisher) PublishModelTrainingDecision(
    modelName string,
    trainingResults *ModelTrainingResults,
    datasetInfo *DatasetInfo,
) error {
    decision := &TaskDecision{
        Task:     fmt.Sprintf("train_model_%s", modelName),
        Decision: fmt.Sprintf("Trained %s model with accuracy %.2f", modelName, trainingResults.Accuracy),
        Success:  trainingResults.Accuracy > 0.8,
        Context: map[string]interface{}{
            "decision_type":     "model_training",
            "model_name":        modelName,
            "training_results":  trainingResults,
            "dataset_info":      datasetInfo,
            "node_id":          dp.nodeID,
        },
    }
    
    return dp.PublishTaskDecision(decision)
}

Adding New Encryption Methods

1. Extend Crypto Interface:

// pkg/crypto/interfaces.go
type CryptoProvider interface {
    EncryptForRole(content []byte, role string) ([]byte, error)
    DecryptWithRole(encrypted []byte) ([]byte, error)
    GenerateKeyPair() (KeyPair, error)
    ValidateKey(key string, isPrivate bool) error
}

type KeyPair interface {
    PublicKey() string
    PrivateKey() string
    Type() string
}

2. Implement New Provider:

// pkg/crypto/nacl_crypto.go
type NaClCrypto struct {
    config *config.Config
}

func NewNaClCrypto(cfg *config.Config) *NaClCrypto {
    return &NaClCrypto{config: cfg}
}

func (nc *NaClCrypto) EncryptForRole(content []byte, role string) ([]byte, error) {
    // NaCl/libsodium implementation
    // ...
}

3. Add to Configuration:

# config.yaml
crypto:
  provider: "age" # or "nacl", "pgp", etc.
  age:
    # Age-specific settings
  nacl:
    # NaCl-specific settings

Debugging & Profiling

Debug Configuration

Development Build

# Build with debug information
go build -gcflags="all=-N -l" -o bzzz-debug main.go

# Run with debugger
dlv exec ./bzzz-debug

Runtime Debugging

// Add debug endpoints
func (s *HTTPServer) setupDebugRoutes() {
    if s.config.Debug.Enabled {
        s.router.HandleFunc("/debug/pprof/", pprof.Index)
        s.router.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
        s.router.HandleFunc("/debug/pprof/profile", pprof.Profile)
        s.router.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
        s.router.HandleFunc("/debug/pprof/trace", pprof.Trace)
    }
}

Structured Logging

// Use structured logging throughout
import "github.com/rs/zerolog/log"

func (ac *AgeCrypto) EncryptForRole(content []byte, roleName string) ([]byte, error) {
    logger := log.With().
        Str("component", "age_crypto").
        Str("operation", "encrypt_for_role").
        Str("role", roleName).
        Int("content_size", len(content)).
        Logger()
    
    logger.Debug().Msg("Starting encryption")
    
    // ... encryption logic
    
    logger.Info().
        Int("encrypted_size", len(encrypted)).
        Dur("duration", time.Since(start)).
        Msg("Encryption completed successfully")
    
    return encrypted, nil
}

Performance Profiling

CPU Profiling

# Generate CPU profile
go test -cpuprofile=cpu.prof -bench=. ./pkg/crypto/

# Analyze profile
go tool pprof cpu.prof
(pprof) top10
(pprof) list EncryptForRole
(pprof) web

Memory Profiling

# Generate memory profile
go test -memprofile=mem.prof -bench=. ./pkg/crypto/

# Analyze memory usage
go tool pprof mem.prof
(pprof) top10 -cum
(pprof) list NewAgeCrypto

Benchmarking

// pkg/crypto/age_crypto_bench_test.go
func BenchmarkAgeCrypto_EncryptForRole(b *testing.B) {
    cfg := &config.Config{/* test config */}
    ac := NewAgeCrypto(cfg)
    content := make([]byte, 1024) // 1KB test content
    
    b.ResetTimer()
    b.ReportAllocs()
    
    for i := 0; i < b.N; i++ {
        _, err := ac.EncryptForRole(content, "backend_developer")
        if err != nil {
            b.Fatal(err)
        }
    }
}

func BenchmarkDHTStorage_StoreRetrieve(b *testing.B) {
    storage := setupTestDHTStorage(b)
    content := generateTestContent(1024)
    
    b.Run("Store", func(b *testing.B) {
        for i := 0; i < b.N; i++ {
            addr := fmt.Sprintf("test/role/project/task/%d", i)
            err := storage.StoreUCXLContent(addr, content, "test_role", "benchmark")
            if err != nil {
                b.Fatal(err)
            }
        }
    })
    
    b.Run("Retrieve", func(b *testing.B) {
        // Pre-populate content
        for i := 0; i < b.N; i++ {
            addr := fmt.Sprintf("test/role/project/task/%d", i)
            _, _, err := storage.RetrieveUCXLContent(addr)
            if err != nil {
                b.Fatal(err)
            }
        }
    })
}

Contributing Guidelines

Code Submission Process

1. Fork & Branch:

git clone https://github.com/your-username/bzzz.git
cd bzzz
git checkout -b feature/your-feature-name

2. Development Workflow:

# Make changes
# Add tests
make test
make lint

# Commit changes
git add .
git commit -m "feat: add custom decision type support

- Add CustomDecision struct with validation
- Implement PublishCustomDecision method  
- Add API endpoint with proper error handling
- Include comprehensive tests and documentation

Cross-references:
- pkg/ucxl/decision_publisher.go: Core implementation
- api/handlers.go: HTTP API integration  
- docs/API_REFERENCE.md: API documentation update"

3. Pull Request:

git push origin feature/your-feature-name
# Create PR via GitHub interface

Commit Message Format

Use conventional commits format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring
• test: Test additions/modifications
• chore: Build system, dependencies

Cross-References: Always include relevant cross-references:

Cross-references:
- pkg/crypto/age_crypto.go:123: Implementation detail
- docs/SECURITY.md: Security implications
- tests/integration/crypto_test.go: Test coverage

Code Review Checklist

For Authors

• All tests pass (make test)
• Code is formatted (make fmt)
• Linting passes (make lint)
• Documentation updated
• Cross-references added
• Performance considered
• Security implications reviewed

for Reviewers

• Code follows established patterns
• Error handling is comprehensive
• Tests cover edge cases
• Documentation is accurate
• Security model is maintained
• Performance impact is acceptable

Cross-Reference: Full contributing guide in docs/CONTRIBUTING.md

Advanced Topics

Custom Consensus Algorithms

To implement alternative consensus algorithms:

1. Define Interface:

// pkg/election/consensus.go
type ConsensusProvider interface {
    ProposeCandidate(candidate *ElectionCandidate) error
    Vote(candidateID string, vote bool) error
    GetWinner() (*ElectionCandidate, error)
    IsComplete() bool
}

2. Implement Algorithm:

// pkg/election/pbft_consensus.go
type PBFTConsensus struct {
    nodes     map[string]*Node
    proposals map[string]*Proposal
    votes     map[string]map[string]bool
    threshold int
}

func (p *PBFTConsensus) ProposeCandidate(candidate *ElectionCandidate) error {
    // PBFT implementation
}

3. Register in Factory:

// pkg/election/factory.go
func NewConsensusProvider(algorithm string, config *Config) ConsensusProvider {
    switch algorithm {
    case "raft":
        return NewRaftConsensus(config)
    case "pbft":
        return NewPBFTConsensus(config)
    default:
        return NewRaftConsensus(config) // Default
    }
}

Custom Storage Backends

Implement alternative storage backends:

1. Storage Interface:

// pkg/storage/interfaces.go
type StorageProvider interface {
    Store(key string, content []byte, metadata *Metadata) error
    Retrieve(key string) ([]byte, *Metadata, error)
    Search(query *SearchQuery) ([]*Metadata, error)
    Delete(key string) error
    GetMetrics() *StorageMetrics
}

2. Implementation Example:

// pkg/storage/redis_storage.go
type RedisStorage struct {
    client redis.Client
    crypto *crypto.AgeCrypto
}

func (rs *RedisStorage) Store(key string, content []byte, metadata *Metadata) error {
    // Encrypt content
    encrypted, err := rs.crypto.EncryptForRole(content, metadata.CreatorRole)
    if err != nil {
        return fmt.Errorf("encryption failed: %w", err)
    }
    
    // Store in Redis
    return rs.client.Set(context.Background(), key, encrypted, metadata.TTL).Err()
}

Plugin System

Implement a plugin system for extensibility:

1. Plugin Interface:

// pkg/plugins/interface.go
type Plugin interface {
    Name() string
    Version() string
    Initialize(config map[string]interface{}) error
    Shutdown() error
}

type DecisionPlugin interface {
    Plugin
    ProcessDecision(decision *ucxl.TaskDecision) (*ucxl.TaskDecision, error)
}

type CryptoPlugin interface {
    Plugin
    Encrypt(content []byte, key string) ([]byte, error)
    Decrypt(content []byte, key string) ([]byte, error)
}

2. Plugin Manager:

// pkg/plugins/manager.go
type Manager struct {
    plugins map[string]Plugin
    hooks   map[string][]Plugin
}

func (m *Manager) LoadPlugin(path string) error {
    // Load plugin from shared library
    plug, err := plugin.Open(path)
    if err != nil {
        return err
    }
    
    // Get plugin symbol
    symPlugin, err := plug.Lookup("BzzzPlugin")
    if err != nil {
        return err
    }
    
    // Type assert and register
    bzzzPlugin, ok := symPlugin.(Plugin)
    if !ok {
        return fmt.Errorf("invalid plugin interface")
    }
    
    m.plugins[bzzzPlugin.Name()] = bzzzPlugin
    return bzzzPlugin.Initialize(nil)
}

---

Cross-References

• User Manual: USER_MANUAL.md - End-user guide
• API Reference: API_REFERENCE.md - Complete API docs
• Security Model: SECURITY.md - Security architecture
• Configuration: CONFIG_REFERENCE.md - Config options
• Contributing: CONTRIBUTING.md - Contribution guidelines

BZZZ Developer Guide v2.0 - Complete development documentation for Phase 2B unified architecture with Age encryption and DHT storage.