# CHORUS Complete Documentation

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

---

## Table of Contents

### 1. [Architecture Overview](architecture/README.md)
High-level system architecture, design principles, and component relationships

- [System Architecture](architecture/system-architecture.md)
- [Component Map](architecture/component-map.md)
- [Data Flow](architecture/data-flow.md)
- [Security Architecture](architecture/security.md)
- [Deployment Architecture](architecture/deployment.md)

### 2. [Command-Line Tools](commands/README.md)
Entry points and command-line interfaces

- [chorus-agent](commands/chorus-agent.md) - Autonomous agent binary
- [chorus-hap](commands/chorus-hap.md) - Human Agent Portal
- [chorus](commands/chorus.md) - Compatibility wrapper (deprecated)

### 3. [Core Packages](packages/README.md)
Public API packages in `pkg/`

#### Execution & AI
- [pkg/execution](packages/execution.md) - Task execution engine and Docker sandboxing
- [pkg/ai](packages/ai.md) - AI provider interfaces and abstractions
- [pkg/providers](packages/providers.md) - Concrete AI provider implementations

#### Coordination & Distribution
- [pkg/slurp](packages/slurp/README.md) - Distributed coordination system
  - [alignment](packages/slurp/alignment.md) - Goal alignment
  - [context](packages/slurp/context.md) - Context management
  - [distribution](packages/slurp/distribution.md) - Work distribution
  - [intelligence](packages/slurp/intelligence.md) - Intelligence layer
  - [leader](packages/slurp/leader.md) - Leadership coordination
  - [roles](packages/slurp/roles.md) - Role assignments
  - [storage](packages/slurp/storage.md) - Distributed storage
  - [temporal](packages/slurp/temporal.md) - Time-based coordination
- [pkg/coordination](packages/coordination.md) - Task coordination primitives
- [pkg/election](packages/election.md) - Leader election algorithms
- [pkg/dht](packages/dht.md) - Distributed hash table

#### Security & Cryptography
- [pkg/crypto](packages/crypto.md) - Encryption and cryptographic primitives
- [pkg/shhh](packages/shhh.md) - Secrets management system
- [pkg/security](packages/security.md) - Security policies and validation

#### Validation & Compliance
- [pkg/ucxl](packages/ucxl.md) - UCXL validation and enforcement
- [pkg/ucxi](packages/ucxi.md) - UCXI integration

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

### 4. [Internal Packages](internal/README.md)
Private implementation packages in `internal/`

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

### 5. [API Layer](api/README.md)
HTTP API and external interfaces

- [API Overview](api/overview.md)
- [HTTP Server](api/http-server.md)
- [Setup Manager](api/setup-manager.md)
- [Authentication](api/authentication.md)
- [API Reference](api/reference.md)

### 6. [Deployment](deployment/README.md)
Deployment configurations and procedures

- [Docker Setup](deployment/docker.md)
- [Configuration Files](deployment/configuration.md)
- [Environment Variables](deployment/environment.md)
- [Production Deployment](deployment/production.md)
- [Development Setup](deployment/development.md)

### 7. [Diagrams](diagrams/README.md)
Visual documentation and architecture diagrams

- [System Overview](diagrams/system-overview.md)
- [Component Interactions](diagrams/component-interactions.md)
- [Sequence Diagrams](diagrams/sequences.md)
- [Data Flow Diagrams](diagrams/data-flow.md)

---

## 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](architecture/README.md)
2. Read [System Architecture](architecture/system-architecture.md)
3. Explore [Command-Line Tools](commands/README.md)
4. Deep dive into specific [packages](packages/README.md) as needed

### For Understanding a Specific Feature
1. Check the [Component Map](architecture/component-map.md)
2. Read the specific package documentation
3. Review relevant [diagrams](diagrams/README.md)
4. See [API Reference](api/reference.md) if applicable

### For Deployment
1. Read [Deployment Overview](deployment/README.md)
2. Follow [Docker Setup](deployment/docker.md)
3. Configure using [Configuration Files](deployment/configuration.md)
4. Review [Production Deployment](deployment/production.md)

### For Contributing
1. Understand [Architecture Overview](architecture/README.md)
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](packages/execution.md)
- External links use full URLs: [Docker Documentation](https://docs.docker.com/)
- Code references link to specific sections: [TaskExecutionEngine](packages/execution.md#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](maintenance.md).

---

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