Update branding assets and deployment configurations

- Enhanced moebius ring logo design in Blender - Updated Docker Compose for website-only deployment with improved config - Enhanced teaser layout with updated branding integration - Added installation and setup documentation - Consolidated planning and reports documentation - Updated gitignore to exclude Next.js build artifacts and archives 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-27 07:45:08 +10:00
parent 8162496c11
commit 4ed167e734
38 changed files with 13841 additions and 6 deletions
--- a/reports/README.md
+++ b/reports/README.md
@@ -0,0 +1,380 @@
+# CHORUS Services - Distributed AI Orchestration Platform
+
+**CHORUS Services** eliminates context loss, reduces hallucinations, and enables scalable multi-agent collaboration through sophisticated context management and distributed reasoning architecture.
+
+## Quick Start
+
+```bash
+# Initialize submodules (first time only)
+./chorus.sh init
+
+# Login to Docker registry
+./chorus.sh login
+
+# Build and push images to registry
+./chorus.sh build
+
+# Start all services
+./chorus.sh start
+
+# Check service health
+./chorus.sh health
+```
+
+**Access Points:**
+**Marketing Website**: https://www.chorus.services (production)
+**Dashboard**: https://dashboard.chorus.services (production)
+**API**: https://api.chorus.services (production)
+**Grafana Monitoring**: http://localhost:3002 (admin/chorusadmin)
+**Prometheus Metrics**: http://localhost:9092
+
+**Local Development:**
+- Dashboard: http://localhost:3001
+- API Docs: http://localhost:8087/docs
+
+## Architecture Overview
+
+CHORUS Services integrates five core components into a sophisticated unified platform:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     CHORUS Services Platform                     │
+├─────────────────────────────────────────────────────────────────┤
+│  WHOOSH Orchestrator         │  Monitoring & Analytics           │
+│  - Workflow Management        │  - Prometheus Metrics             │
+│  - Agent Coordination         │  - Grafana Dashboards             │  
+│  - Task Distribution          │  - Real-time Health Monitoring    │
+├─────────────────────────────────────────────────────────────────┤
+│  BZZZ P2P Network             │  SLURP Context Management         │
+│  - Agent Mesh Networking      │  - Hierarchical Context Storage   │
+│  - Peer Discovery             │  - Semantic Search & Indexing     │
+│  - Distributed Coordination   │  - Multi-language SDK Support     │
+├─────────────────────────────────────────────────────────────────┤
+│  COOEE Feedback System (RL Context SLURP Integration)            │
+│  - Performance-based Learning  │  - Context Relevance Tuning      │
+│  - Agent Feedback Collection   │  - Role-based Access Control     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### WHOOSH - Orchestration Engine
+**Enterprise workflow management** for distributed AI agents
+**Visual workflow coordination** with sophisticated React Flow integration
+**Real-time performance monitoring** and comprehensive metrics
+**Multi-agent task distribution** with intelligent coordination
+
+### BZZZ - P2P Agent Coordination
+**Mesh networking architecture** with libp2p for resilient communication
+**Automatic peer discovery** through sophisticated networking protocols
+**Distributed task coordination** without single points of failure
+**High-performance networking** implementation in Go
+
+### SLURP - Context Curator Service
+**Sophisticated context curation** from Hypercore logs based on agent roles and operational triggers
+**Role-based context filtering** for permissions management, deprecation handling, and feature evolution
+**SQL-based context delivery** with intelligent relevance scoring algorithms
+**Seamless HCFS integration** for transparent filesystem-based context access
+
+### COOEE - Feedback & Learning System
+**Advanced reinforcement learning** for context relevance optimization
+**Comprehensive agent feedback collection** with sophisticated rating mechanisms
+**Role-based access control** and intelligent context filtering
+**Continuous improvement** through real-world performance data analysis
+
+### Monitoring & Analytics
+**Comprehensive Prometheus metrics** collection across all platform services
+**Sophisticated Grafana dashboards** for visualization and intelligent alerting
+**Enterprise-grade health monitoring** and performance tracking
+**Complete audit trails** with sophisticated traceability mechanisms
+
+## Management Commands
+
+The `./chorus.sh` script provides unified management:
+
+```bash
+# Service Management
+./chorus.sh start          # Start all services (registry images)
+./chorus.sh stop           # Stop all services  
+./chorus.sh restart        # Restart all services
+./chorus.sh status         # Show service status
+./chorus.sh dev            # Start in development mode (local builds)
+
+# Docker Registry Operations  
+./chorus.sh login          # Login to Docker registry
+./chorus.sh build          # Build and push all images to registry
+./chorus.sh pull           # Pull latest images from registry
+
+# Individual Component Builds
+./build-and-push.sh website        # Build and push website only
+./build-and-push.sh whoosh-backend # Build and push WHOOSH backend only
+./build-and-push.sh bzzz           # Build and push BZZZ coordinator only
+
+# Production Deployment
+./chorus.sh deploy         # Deploy to Docker Swarm (production)
+./chorus.sh undeploy       # Remove from Docker Swarm
+
+# Development & Maintenance
+./chorus.sh update         # Update submodules to latest
+./chorus.sh logs [service] # View logs
+./chorus.sh health         # Check service health
+./chorus.sh clean          # Clean up resources
+
+# First-time Setup
+./chorus.sh init           # Initialize git submodules
+```
+
+## Service Endpoints
+
+| Service | Port | Purpose | Health Check |
+|---------|------|---------|--------------|
+| **WHOOSH Dashboard** | 3001 | Web UI for orchestration | http://localhost:3001 |
+| **WHOOSH API** | 8087 | REST API + WebSocket | http://localhost:8087/health |
+| **BZZZ Coordinator** | 8080 | P2P coordination API | http://localhost:8080/health |
+| **SLURP API** | 8088 | Context management API | http://localhost:8088/health |
+| **COOEE RL Tuner** | 8089 | Feedback & learning API | http://localhost:8089/health |
+| **Grafana** | 3002 | Monitoring dashboards | http://localhost:3002 |
+| **Prometheus** | 9092 | Metrics collection | http://localhost:9092 |
+| **PostgreSQL** | 5433 | Database | - |
+| **Redis** | 6380 | Cache & message queue | - |
+
+## Project Structure
+
+```
+chorus.services/
+├── 📋 README.md                    # This file
+├── 🎛️ chorus.sh                   # Management script
+├── 🐳 docker-compose.yml          # Service orchestration
+├── 🗄️ init-db.sql                 # Database initialization
+├── 📊 monitoring/                  # Monitoring configuration
+│   ├── prometheus.yml
+│   └── grafana/
+├── 📚 docs/                        # Project documentation
+│   ├── PROJECT_PLAN.md
+│   ├── DESIGN.md
+│   └── Copywriting.md
+└── 🧩 modules/                     # Git submodules
+    ├── whoosh/                     # Orchestration platform
+    ├── bzzz/                       # P2P coordination
+    ├── slurp/                      # Context management (HCFS)
+    └── website/                    # Marketing website (Next.js)
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+Key configuration options in `docker-compose.yml`:
+
+- **Database**: `DATABASE_URL`, `POSTGRES_*`
+- **Redis**: `REDIS_URL`
+- **CORS**: `CORS_ORIGINS`
+- **Logging**: `LOG_LEVEL`
+- **Environment**: `ENVIRONMENT` (development/production)
+
+### Adding New Agents
+Edit agent configurations in `modules/whoosh/config/whoosh.yaml`:
+
+```yaml
+whoosh:
+  agents:
+    my_agent:
+      name: "My Agent"
+      endpoint: "http://192.168.1.100:11434"
+      model: "llama3.1"
+      specialization: "coding"
+      capabilities: ["python", "javascript"]
+```
+
+## 🔧 Development Setup
+
+### Prerequisites
+- Docker and Docker Compose
+- Git
+- 8GB+ RAM recommended
+- Access to Ollama agents on network
+
+### First-Time Setup
+```bash
+# Clone with submodules
+git clone --recursive <repository-url>
+cd chorus.services
+
+# Or initialize submodules if already cloned
+./chorus.sh init
+
+# Login to Docker registry
+./chorus.sh login
+
+# Build and push all images to registry
+./chorus.sh build
+
+# Start services
+./chorus.sh start
+```
+
+### Development Workflow
+```bash
+# Development mode (local builds, live reloading)
+./chorus.sh dev
+
+# Update submodules to latest
+./chorus.sh update
+
+# Rebuild and push after changes
+./chorus.sh build
+
+# Pull latest images from registry
+./chorus.sh pull
+
+# View logs during development
+./chorus.sh logs
+
+# Check service health
+./chorus.sh health
+
+# Restart after changes
+./chorus.sh restart
+```
+
+### Production Deployment
+```bash
+# Deploy to Docker Swarm (production)
+./chorus.sh deploy
+
+# Access at https://*.home.deepblack.cloud endpoints
+
+# Remove from swarm
+./chorus.sh undeploy
+```
+
+## 🚀 Git Submodules Guide
+
+CHORUS Services uses git submodules to integrate independent components:
+
+### Basic Submodule Commands
+```bash
+# Initialize submodules (first time)
+git submodule init
+git submodule update
+
+# Update to latest commits
+git submodule update --remote
+
+# Check submodule status
+git submodule status
+
+# Enter a submodule to work on it
+cd modules/whoosh
+git checkout main
+# Make changes, commit, push
+
+# Return to main project and commit submodule updates
+cd ../..
+git add modules/whoosh
+git commit -m "Update whoosh submodule"
+```
+
+### Working with Submodules
+- **Each submodule** is an independent git repository
+- **Changes within submodules** must be committed in the submodule first
+- **Parent project** tracks specific commits of each submodule
+- **Use `./chorus.sh update`** to pull latest changes from all submodules
+
+## 📊 Monitoring & Metrics
+
+### Key Metrics Tracked
+- **Agent Performance**: Response time, throughput, availability
+- **Context Management**: Search performance, storage efficiency  
+- **P2P Network**: Peer connectivity, message latency
+- **System Health**: CPU, memory, GPU utilization
+- **Workflow Execution**: Success rate, execution time
+
+### Grafana Dashboards
+- **CHORUS Overview**: Platform-wide health and metrics
+- **Agent Performance**: Individual agent monitoring
+- **Context Analytics**: SLURP usage and performance
+- **Network Health**: BZZZ P2P network monitoring
+
+## 🛡️ Security Features
+
+- **Authentication**: JWT tokens and API key support
+- **Role-based Access**: Context filtering by agent roles
+- **Audit Trails**: Complete logging of all operations
+- **Network Security**: Internal container networking
+- **Data Privacy**: Encrypted context storage
+
+## 🤝 Contributing
+
+### Component Development
+Each component can be developed independently:
+
+```bash
+# Work on WHOOSH orchestrator
+cd modules/whoosh
+# Follow component-specific development guide
+
+# Work on BZZZ P2P system  
+cd modules/bzzz
+# Follow Go development practices
+
+# Work on SLURP context system
+cd modules/slurp
+# Follow Python development practices
+```
+
+### Integration Testing
+```bash
+# Test full platform integration
+./chorus.sh start
+./chorus.sh health
+
+# Run component-specific tests
+cd modules/[component]
+# Follow component test procedures
+```
+
+## 📈 Performance Metrics
+
+**Production-Ready Performance:**
+- **API Response Times**: <5ms cached, <50ms uncached
+- **Context Search**: <100ms semantic search across 1000+ contexts
+- **P2P Network**: <10ms peer communication latency
+- **Workflow Execution**: Support for complex multi-agent workflows
+- **Concurrent Agents**: Scales to 10+ simultaneous agents
+
+## 🎯 Use Cases
+
+### Enterprise AI Development
+- **Multi-agent software development** with specialized AI agents
+- **Context-aware code generation** with organizational knowledge
+- **Distributed task execution** across development infrastructure
+
+### Research & Collaboration  
+- **AI agent coordination research** with real-world deployment
+- **Context management studies** with hierarchical storage
+- **Distributed systems research** with P2P networking
+
+### Production AI Systems
+- **Enterprise AI orchestration** with monitoring and compliance
+- **Context-aware AI applications** with persistent memory
+- **Scalable multi-agent deployments** with automatic coordination
+
+## 📞 Support & Documentation
+
+- **🛠️ Management**: `./chorus.sh` for all operations
+- **📋 Component Docs**: See individual `modules/*/README.md`
+- **🔧 API Documentation**: http://localhost:8087/docs (when running)
+- **📊 Monitoring**: http://localhost:3002 (Grafana dashboards)
+
+---
+
+## 🎉 Welcome to CHORUS Services!
+
+**CHORUS Services represents the future of distributed AI orchestration**, providing enterprise-ready tools for context management, agent coordination, and intelligent workflow execution.
+
+🎵 *"Individual components make music, but CHORUS Services creates symphony."*
+
+**Ready to orchestrate your AI agents?**
+```bash
+./chorus.sh start
+```