Skip to content

HiveMatrix Documentation

Welcome to the HiveMatrix platform documentation. HiveMatrix is a modular, AI-maintainable platform for MSP (Managed Service Provider) operations.

Core Documentation

Developer Guides

Service Documentation

Detailed documentation for each of the 8 HiveMatrix services:

Core Services

  • Core - Authentication & JWT management (port 5000)
  • Nexus - HTTPS gateway & HTML injection proxy (port 443)
  • Helm - Orchestration & centralized logging (port 5004)

Application Services

  • Codex - Master data hub (port 5010)
  • Ledger - Billing & invoicing with integrated archival (port 5030)
  • KnowledgeTree - Graph-based knowledge management (port 5020)
  • Brainhair - AI chat assistant with Claude Code CLI (port 5050)
  • Beacon - Real-time ticket dashboard (port 5001)

What is HiveMatrix?

HiveMatrix is a collection of 8 independent, fully functional applications that work together to provide a complete MSP platform:

  • Client Management - Company and contact tracking via Codex
  • Billing & Invoicing - Automated billing calculations and archival via Ledger (Archive merged)
  • Knowledge Management - Neo4j graph-based knowledge system with KnowledgeTree
  • Ticket Dashboard - Real-time PSA ticket monitoring via Beacon
  • AI Integration - Claude Code CLI with PHI/CJIS filtering via Brainhair
  • Service Orchestration - Centralized logging and management via Helm
  • Authentication - Redis-backed sessions with JWT revocation via Core
  • Gateway - HTTPS termination and UI composition via Nexus

Core Principles

  1. AI Maintainability - Each application remains small, focused, and simple
  2. Modularity - Independent services that can be composed together
  3. Simplicity - Simple, explicit patterns over complex, "magical" ones

Getting Started

Installation

# Clone the orchestration system
git clone https://github.com/skelhammer/hivematrix-helm
cd hivematrix-helm

# Run the installation
./start.sh

The installation will: 1. Install system dependencies (PostgreSQL, Neo4j, Java, Python) 2. Set up Keycloak authentication server 3. Clone and configure Core and Nexus (required components) 4. Set up databases 5. Start all services

Default Credentials

  • Username: admin
  • Password: admin

Important: Change the default password after first login!

Access

  • Main Interface: https://YOUR_SERVER_IP:443 (use your server's actual IP address, not localhost)
  • Helm Dashboard: http://localhost:5004 (local only)
  • Keycloak Admin: http://localhost:8080 (local only)

Architecture Overview

HiveMatrix uses a monolithic service pattern where each module is a self-contained application with:

  • Server-side rendering (returns complete HTML)
  • Own database (no cross-service database access)
  • Optional data APIs (JSON endpoints)

Authentication Flow

  1. User logs in via Keycloak (through Nexus proxy)
  2. Keycloak validates credentials
  3. Core mints a HiveMatrix JWT with user permissions
  4. Nexus stores JWT in session cookie
  5. Backend services verify JWT using Core's public key

Key Components (8 Services)

  • Core (5000) - Redis-backed sessions, JWT management, session revocation
  • Nexus (443) - HTTPS gateway, OAuth2 flow, CSS injection, UI composition
  • Helm (5004) - Service orchestration, PostgreSQL centralized logging, security audits
  • Codex (5010) - Master data management (companies, contacts, assets, PSA/RMM sync)
  • Ledger (5030) - Billing calculation, invoicing, and integrated archival (Archive merged)
  • KnowledgeTree (5020) - Neo4j graph-based knowledge with AI context API
  • Brainhair (5050) - Claude Code CLI with Presidio PHI/CJIS filtering and approval workflow
  • Beacon (5001) - Real-time ticket dashboard with SLA monitoring

Recent Improvements (2025-11-22)

HiveMatrix has been significantly enhanced with production-ready features:

Infrastructure & Reliability

  • Automated Database Backups - Daily backups with 30-day retention
  • Comprehensive Health Checks - Component-level monitoring across all services
  • Redis Session Persistence - Sessions survive service restarts
  • Structured JSON Logging - Correlation IDs for distributed tracing

API & Development

  • OpenAPI/Swagger Documentation - Interactive API docs at /docs endpoint
  • RFC 7807 Error Responses - Standardized machine-readable error format
  • Per-User Rate Limiting - JWT-based rate limiting (prevents shared IP abuse)
  • Pre-commit Hooks - Optional code quality automation (black, isort, flake8)

Observability

  • Enhanced Log Viewer - Filter by correlation ID, user, service, or level
  • Request Timeouts - 30-second default prevents hanging requests
  • Service Health Dashboard - Real-time health status with latency metrics

See HIVEMATRIX-TODO.md for complete implementation details.

Development

Running the Development Environment

cd hivematrix-helm
./start.sh

Stopping Services

./stop.sh

Viewing Logs

# Via CLI tool
cd hivematrix-helm
source pyenv/bin/activate
python logs_cli.py --service core --tail 50

# Or check log files directly
tail -f logs/core.stdout.log

Configuration

All configuration is centralized in hivematrix-helm:

  • apps_registry.json - Source of truth for all apps
  • master_config.json - System-wide configuration
  • instance/configs/ - Service-specific configs (auto-generated)

Backup & Restore

# Create backup
sudo python3 backup.py

# Restore from backup
./stop.sh
sudo python3 restore.py /tmp/hivematrix_backup_*.zip
./start.sh

Documentation Structure

Core Documentation

  • ARCHITECTURE.md - Architecture index with navigation (split into 3 parts)
  • ARCHITECTURE-CORE.md - Core concepts (sections 1-7)
    • Core philosophy and goals
    • Monolithic service pattern
    • End-to-end authentication flow
    • Service-to-service communication
    • Smart proxy composition (Nexus)
    • Configuration management & auto-installation
    • AI instructions for building new services
  • ARCHITECTURE-DEVELOPMENT.md - Development & operations (sections 8-15)
    • Running the development environment
    • Keycloak auto-configuration
    • Backup & restore system
    • Development & debugging tools
    • Security architecture
    • Design system & BEM classes
    • Database best practices
    • External system integration

  • ARCHITECTURE-SERVICES.md - Service-specific (sections 16-22)

    • Brainhair AI assistant with Claude Code CLI
    • Service token caching (90% Core load reduction)
    • Production features (Redis, rate limiting, logging, health checks, OpenAPI)
    • Centralized logging architecture (Helm)
    • Billing architecture (Ledger with Archive integration)
    • Graph database pattern (KnowledgeTree)
    • Version history (v3.0 to v4.2)

  • installation.md - Installation guide (438 lines)

  • System requirements
  • Quick start installation
  • Step-by-step setup
  • Service verification
  • Troubleshooting

  • Autostart configuration

  • configuration.md - Configuration reference (480 lines)

  • Master configuration structure
  • Service registry management
  • Database settings
  • Port assignments
  • SSL/TLS setup

  • Performance tuning

  • services-overview.md - Service descriptions (272 lines)

  • Core services (Core, Nexus, Helm)
  • Application services (Codex, Ledger, KnowledgeTree, Brainhair)
  • Service dependencies and APIs

  • Key features and endpoints

  • security.md - Security hardening (271 lines)

  • Zero-trust network model
  • Firewall configuration
  • Service binding requirements
  • Security verification
  • Production deployment hardening

  • Common security issues

  • ai-tools-reference.md - Brainhair AI tools

  • Complete list of AI tools
  • Tool usage examples
  • Approval flow documentation
  • PHI/CJIS filtering guide
  • Creating custom tools

Developer Documentation

  • CLAUDE.md - AI assistant guidelines (714 lines)
  • Understanding HiveMatrix structure
  • Making code changes
  • Following conventions
  • Debugging issues
  • Testing checklist

Status & Planning

  • HIVEMATRIX-TODO.md - Current status and completed work
  • Production readiness checklist
  • Completed improvements (8 major systems)
  • Pending tasks and optional bug fixes
  • Future enhancements (deferred until scaling)

  • Time invested tracking

  • BACKUP.md - Backup and restore procedures

  • Automated daily backups via systemd
  • Manual backup procedures
  • Restoration guide

  • 30-day retention policy

  • SECURITY-AUDIT-2025-11-22.md - Security audit results

  • SQL injection check (clean)
  • Hardcoded secrets check (clean)
  • Authentication architecture validation
  • Port binding verification
  • Firewall configuration recommendations

Contributing

When contributing to HiveMatrix:

  1. Read ARCHITECTURE.md thoroughly
  2. Follow the monolithic service pattern
  3. Keep services small and focused
  4. Use server-side rendering
  5. Never access another service's database directly
  6. Update documentation for architectural changes

License

HiveMatrix is released under the MIT License. See LICENSE for details.

Support

For issues and questions: - GitHub Issues: HiveMatrix Repositories - Documentation: This site

Version

Documentation Version: 1.0 Architecture Version: 4.2 (See ARCHITECTURE.md version history)

Version 1.0 - Comprehensive Documentation Overhaul (2025-11-22): - Complete rewrite of all 8 service documentation pages (19,000+ lines) - Enhanced GitHub Pages features (TOC, hyperlinks, cross-references, navigation) - Updated ARCHITECTURE.md to v4.2 with 5 new sections - Archive merged into Ledger (no longer separate service) - Brainhair documented with Claude Code CLI architecture - Production features documented across all services - Updated all supporting documentation (installation, configuration, security) - Comprehensive "See Also" sections linking related documentation