CHORUS/docs/comprehensive/README.md

CHORUS Complete Documentation

Version: 1.0.0 Generated: 2025-09-30 Status: Complete comprehensive documentation of CHORUS system

---

Table of Contents

1. Architecture Overview

High-level system architecture, design principles, and component relationships

• System Architecture
• Component Map
• Data Flow
• Security Architecture
• Deployment Architecture

2. Command-Line Tools

Entry points and command-line interfaces

• chorus-agent - Autonomous agent binary
• chorus-hap - Human Agent Portal
• chorus - Compatibility wrapper (deprecated)

3. Core Packages

Public API packages in pkg/

Execution & AI

• pkg/execution - Task execution engine and Docker sandboxing
• pkg/ai - AI provider interfaces and abstractions
• pkg/providers - Concrete AI provider implementations

Coordination & Distribution

• pkg/slurp - Distributed coordination system
  • alignment - Goal alignment
  • context - Context management
  • distribution - Work distribution
  • intelligence - Intelligence layer
  • leader - Leadership coordination
  • roles - Role assignments
  • storage - Distributed storage
  • temporal - Time-based coordination
• pkg/coordination - Task coordination primitives
• pkg/election - Leader election algorithms
• pkg/dht - Distributed hash table

Security & Cryptography

• pkg/crypto - Encryption and cryptographic primitives
• pkg/shhh - Secrets management system
• pkg/security - Security policies and validation

Validation & Compliance

• pkg/ucxl - UCXL validation and enforcement
• pkg/ucxi - UCXI integration

Infrastructure

• pkg/mcp - Model Context Protocol implementation
• pkg/repository - Git repository operations
• pkg/metrics - Monitoring and telemetry
• pkg/health - Health check system
• pkg/config - Configuration management
• pkg/bootstrap - System bootstrapping
• pkg/pubsub - Pub/sub messaging
• pkg/storage - Storage abstractions
• pkg/types - Common type definitions
• pkg/version - Version information
• pkg/web - Web server and static assets
• pkg/agentid - Agent identity management
• pkg/prompt - Prompt management
• pkg/shutdown - Graceful shutdown coordination
• pkg/hmmm - HMMM integration
• pkg/hmmm_adapter - HMMM adapter
• pkg/integration - Integration utilities
• pkg/protocol - Protocol definitions

4. Internal Packages

Private implementation packages in internal/

• internal/agent - Agent core implementation
• internal/hapui - Human Agent Portal UI
• internal/licensing - License validation and enforcement
• internal/logging - Logging infrastructure
• internal/config - Internal configuration
• internal/runtime - Runtime environment
• internal/backbeat - Background processing
• internal/p2p - Peer-to-peer networking

5. API Layer

HTTP API and external interfaces

• API Overview
• HTTP Server
• Setup Manager
• Authentication
• API Reference

6. Deployment

Deployment configurations and procedures

• Docker Setup
• Configuration Files
• Environment Variables
• Production Deployment
• Development Setup

7. Diagrams

Visual documentation and architecture diagrams

• System Overview
• Component Interactions
• Sequence Diagrams
• Data Flow Diagrams

---

Quick Reference

Key Components

Component	Purpose	Status	Location
chorus-agent	Autonomous AI agent	Production	cmd/agent
Task Execution Engine	Sandboxed code execution	Production	pkg/execution
SLURP	Distributed coordination	Production	pkg/slurp
UCXL Validation	Compliance enforcement	Production	pkg/ucxl
Crypto/SHHH	Security & secrets	Production	pkg/crypto, pkg/shhh
HAP	Human Agent Portal	Beta	cmd/hap, internal/hapui
MCP Integration	Model Context Protocol	Beta	pkg/mcp
DHT	Distributed hash table	Alpha	pkg/dht
AI Providers	Multi-provider AI	Production	pkg/ai, pkg/providers

Implementation Status Legend

• ✅ Production: Fully implemented, tested, and production-ready
• 🔶 Beta: Implemented with core features, undergoing testing
• 🔷 Alpha: Basic implementation, experimental
• 🔴 Stubbed: Interface defined, implementation incomplete
• ⚪ Mocked: Mock/simulation for development

File Statistics

• Total Go files: 221 (excluding vendor)
• Packages: 30+ public packages in pkg/
• Internal packages: 8 in internal/
• Entry points: 3 in cmd/
• Lines of code: ~50,000+ (estimated, excluding vendor)

---

How to Use This Documentation

For New Developers

1. Start with Architecture Overview
2. Read System Architecture
3. Explore Command-Line Tools
4. Deep dive into specific packages as needed

For Understanding a Specific Feature

1. Check the Component Map
2. Read the specific package documentation
3. Review relevant diagrams
4. See API Reference if applicable

For Deployment

1. Read Deployment Overview
2. Follow Docker Setup
3. Configure using Configuration Files
4. Review Production Deployment

For Contributing

1. Understand Architecture Overview
2. Review relevant package documentation
3. Check implementation status in component tables
4. Follow coding patterns shown in examples

---

Documentation Conventions

Code References

• File paths are shown relative to repository root: pkg/execution/engine.go
• Line numbers included when specific: pkg/execution/engine.go:125-150
• Functions referenced with parentheses: ExecuteTask(), NewEngine()
• Types referenced without parentheses: TaskExecutionRequest, Engine

Status Indicators

• [PRODUCTION] - Fully implemented and tested
• [BETA] - Core features complete, testing in progress
• [ALPHA] - Basic implementation, experimental
• [STUB] - Interface defined, implementation incomplete
• [MOCK] - Simulated/mocked for development
• [DEPRECATED] - Scheduled for removal

Cross-References

• Internal links use relative paths: See execution engine
• External links use full URLs: Docker Documentation
• Code references link to specific sections: TaskExecutionEngine

Diagrams

• ASCII diagrams for simple flows
• Mermaid diagrams for complex relationships (convert to SVG with pandoc)
• Sequence diagrams for interactions
• Component diagrams for architecture

---

Maintenance

This documentation was generated through comprehensive code analysis and should be updated when:

• New packages are added
• Significant architectural changes occur
• Implementation status changes (stub → alpha → beta → production)
• APIs change or are deprecated

To regenerate specific sections, see Documentation Generation Guide.

---

Contact & Support

For questions about this documentation or the CHORUS system:

• Repository: https://gitea.chorus.services/tony/CHORUS
• Issues: https://gitea.chorus.services/tony/CHORUS/issues
• Documentation issues: Tag with documentation label