Skip to content

Services Overview

HiveMatrix is composed of 8 independent services that work together to provide a complete MSP platform. Each service is a self-contained application with its own database and user interface, communicating via JWT-authenticated REST APIs.

Core Services

These services are required for HiveMatrix to function.

Core

Repository: hivematrix-core Port: 5000 Database: Redis (session storage) + PostgreSQL (optional) → Detailed Documentation

The authentication and service registry hub. Core handles:

  • JWT Token Management: Issues and validates RS256-signed HiveMatrix JWTs
  • Keycloak Integration: Exchanges OAuth2 tokens for HiveMatrix tokens
  • Session Management: Redis-backed sessions with revocation support
  • Public Key Distribution: JWKS endpoint for JWT verification
  • Service-to-Service Auth: Issues 5-minute service tokens for inter-service calls
  • Permission Management: Maps Keycloak groups to admin/technician/billing/client levels

Core is the first service started and other services depend on it for authentication.

Production Features: - Redis Session Persistence - Sessions survive service restarts - Per-User Rate Limiting - JWT subject-based (10/min login, 20/min token exchange) - Structured JSON Logging - Correlation IDs for distributed tracing - RFC 7807 Error Responses - Standardized machine-readable errors - Health Checks - Redis, disk space monitoring

Key Endpoints: - /api/token/exchange - Exchange Keycloak token for HiveMatrix JWT - /api/token/validate - Validate JWT and check session status - /api/token/revoke - Revoke session (logout) - /service-token - Issue service-to-service authentication token - /.well-known/jwks.json - Public keys for JWT verification - /health - Comprehensive health check endpoint

Nexus

Repository: hivematrix-nexus Port: 443 (HTTPS) Database: None (stateless proxy) → Detailed Documentation

The frontend gateway and HTML injection proxy. Nexus provides:

  • HTTPS Termination: SSL/TLS for all services
  • OAuth2 Gateway: Handles complete Keycloak authorization code flow
  • Smart Proxying: Routes requests to backend services with JWT propagation
  • HTML Injection: Injects global CSS, navigation, and dark mode into all service UIs
  • Session Management: Stores JWTs in encrypted Flask session cookies
  • Service Composition: Combines UIs from multiple services seamlessly

Nexus is the only service accessible from the internet (port 443). All other services bind to localhost for security.

Key Features: - BeautifulSoup-based HTML injection for seamless UI composition - JWT validation on every request via Core - Dynamic service routing based on services.json - Global navigation sidebar with theme toggle - Dark mode injection into all backend services - Keycloak proxy for SSO authentication - X-Forwarded headers for backend services

Helm

Repository: hivematrix-helm Port: 5004 Database: PostgreSQL → Detailed Documentation

The orchestration and centralized logging hub. Helm provides:

  • Service Lifecycle Management: Start, stop, restart services with PID tracking
  • Centralized Logging: Aggregate logs from all services to PostgreSQL
  • Health Monitoring: Real-time CPU, memory, uptime tracking
  • Configuration Management: Sync master_config.json to all .flaskenv files
  • Installation Management: Install/update services from Git repositories
  • Security Auditing: Port binding checks and UFW firewall rule generation
  • Backup & Recovery: Automated database and configuration backups

Helm is admin-only and provides both a web dashboard and CLI tools for platform management.

Key Features: - Log Aggregation: All services send structured logs to Helm's PostgreSQL - Log Watcher: Background thread monitors log files for ingestion - CLI Tools: cli.py for service management, logs_cli.py for log viewing - Real-Time Monitoring: Service status dashboard with CPU/memory metrics - Configuration Distribution: One-command sync across all services - Security Audit: Automated port scanning and firewall generation - Install Manager: Git-based service installation and updates

Application Services

These services provide specific business functionality.

Codex

Repository: hivematrix-codex Port: 5010 Database: PostgreSQL → Detailed Documentation

The central data hub and API aggregation point for HiveMatrix. Codex serves as the "rolodex" managing:

  • Companies: Client and vendor information
  • Contacts: People associated with companies
  • Assets: Equipment, licenses, and resources
  • Network Equipment: Routers, switches, access points
  • Third-Party Integration: PSA systems and Datto RMM sync

Codex is the master data source that other services query for company/contact information.

Key Features: - Company hierarchy support (parent/child relationships) - Contact management with roles - Asset tracking with warranty dates - Network topology mapping - Bi-directional sync with PSA/RMM tools - Import/export capabilities

API Endpoints: - /api/companies - Company CRUD operations - /api/contacts - Contact management - /api/assets - Asset tracking - /api/network_equipment - Network device management

Ledger

Repository: hivematrix-ledger Port: 5030 Database: PostgreSQL → Detailed Documentation

Comprehensive billing calculation and invoicing platform with built-in archival. Ledger handles:

  • Billing Calculation: Multi-tier plans, per-item pricing, prepaid hours, ticket billing
  • Override System: 6 types (client, asset, user, manual asset, manual user, custom line items)
  • Invoice Generation: CSV format compatible with QuickBooks/Sage
  • Billing Snapshots: Immutable historical records (merged Archive functionality)
  • Bulk Operations: Generate all invoices at once, ZIP download
  • Dashboard Analytics: Real-time metrics, company comparisons

Ledger integrates with Codex for companies, assets, users, and tickets to automate billing calculations.

Billing Architecture: - 5-Step Calculation: Base plan → Per-item pricing → Overrides → Tickets → Prepaid hours - 6 Override Types: ClientBillingOverride, AssetBillingOverride, UserBillingOverride, ManualAsset, ManualUser, CustomLineItem - Archive Integration: Direct database snapshot creation (no HTTP calls to separate Archive service) - Bulk API Optimization: Single Codex call for all company data (30s → 2s dashboard load)

Key Features: - Multi-Tier Plans: Contract terms (month-to-month, 1-year, 2-year, 3-year) with different rates - Per-Item Pricing: Users, workstations, servers, VMs, switches, firewalls, printers - Backup Billing: Tiered storage (base fee + overage charges) - Ticket Hour Tracking: Automated billable hours from Codex tickets - Prepaid Hours: Monthly or yearly prepaid support packages - Custom Line Items: One-off, recurring, or yearly charges - Billing Snapshots: BillingSnapshot, SnapshotLineItem, ScheduledSnapshot, SnapshotJob models - CSV Export: QuickBooks-compatible invoice format

API Endpoints: - /api/billing/calculate/{account} - Calculate monthly bill - /api/billing/invoice/{account} - Generate CSV invoice - /api/billing/bulk-invoices - Generate all company invoices as ZIP - /api/overrides/* - Manage 6 override types - /archive/api/snapshots/* - Billing snapshot management (merged Archive endpoints)

KnowledgeTree

Repository: hivematrix-knowledgetree Port: 5020 Database: Neo4j (graph database) → Detailed Documentation

Graph-based knowledge management system with AI assistant integration. KnowledgeTree provides:

  • Neo4j Integration: Graph database for hierarchical knowledge with relationships
  • Context System: Structured context API for Brainhair AI assistant
  • Codex Sync: Real-time sync of companies, users, assets, tickets from Codex
  • Hierarchical Organization: Root → Folders → Articles with PARENT_OF relationships
  • Full-Text Search: Score-ranked search across all content
  • Attached Folders: Link related knowledge items dynamically

KnowledgeTree uses Cypher queries to manage complex knowledge hierarchies and provide context to the AI assistant.

Neo4j Architecture: - ContextItem Nodes: id, name, type (root/folder/article), content, metadata - PARENT_OF Relationships: Hierarchical tree structure - Full-Text Index: article_search index on name and content fields - Cypher Queries: GET root items, children, breadcrumbs, search, move operations

Key Features: - Graph-Based Storage: Flexible relationships, not rigid table structures - Context for AI: Brainhair queries /api/context/for-company/{account} for relevant knowledge - Codex Integration: Syncs companies, users, assets, tickets to provide real-time context - Multiple Views: Grid, list, tree visualization modes - Markdown Rendering: Code highlighting, tables, lists - File Attachments: Upload and attach files to articles - Export/Import: Bulk data operations - Admin Dashboard: Neo4j database management

API Endpoints: - /api/items - CRUD operations on ContextItems - /api/items/{id}/children - Get child items - /api/items/{id}/breadcrumbs - Get path from root - /api/search - Full-text search with scores - /api/context/for-company/{account} - Get context for AI assistant - /api/sync/* - Sync companies, users, assets, tickets from Codex

Brainhair

Repository: hivematrix-brainhair Port: 5050 Database: PostgreSQL → Detailed Documentation

AI chat assistant powered by Claude Code CLI with PHI/CJIS filtering. Brainhair provides:

  • Claude Code Integration: Official Anthropic CLI with streaming JSON output
  • Polling Architecture: Server-side response buffers with client polling (500ms)
  • PHI/CJIS Filtering: Microsoft Presidio with custom FirstNameLastInitialOperator
  • Approval Workflow: File-based IPC for human-in-the-loop dangerous operations
  • Contract Alignment: Automated billing alignment from contract analysis
  • Session Management: PostgreSQL persistence with 30-minute idle cleanup
  • Tool System: Python modules in claude_tools/ for service integration

Brainhair provides natural language access to all HiveMatrix services while protecting sensitive information.

Key Features: - Claude Code CLI: Subprocess-based integration with allowed tools (Bash, Read, Grep, Glob, WebFetch, WebSearch) - Polling vs SSE: Server-side response buffers for better proxy compatibility - PHI Filtering: 11 entity types (PERSON, EMAIL, PHONE, SSN, etc.) with custom name anonymization - Approval System: Database-backed approval tracking with /tmp file IPC - Contract Alignment: 5-step workflow (analyze, compare, align, apply, verify) - Session Cleanup: Background thread removes idle sessions after 30 minutes - Tools: codex_tools, ledger_tools, knowledge_tools, datto_tools, session_tools, contract_tools

Example Capabilities: - "What are the open tickets for Company X?" - "Analyze the Example Company contract and align our billing" - "Show me the billing breakdown for November 2024" - "Search the knowledge base for firewall configuration"

Beacon

Repository: hivematrix-beacon Port: 5001 Database: None (stateless - consumes Codex API) → Detailed Documentation

Real-time ticket monitoring dashboard with categorized views. Beacon provides:

  • Ticket Dashboard: 4-section categorized view of active helpdesk tickets
  • Dual Views: Separate dashboards for Helpdesk and Professional Services
  • SLA Monitoring: Visual indicators for overdue, critical, and warning states
  • Agent Filtering: Filter tickets by assigned technician (external_id from Codex)
  • Auto-Refresh: JavaScript polling updates every 60 seconds

Beacon is a stateless read-only service that displays ticket data from Codex's /api/tickets/active endpoint. It never contacts PSA systems directly.

Key Features: - 4-Section Categorization: 1. Open tickets (needs first response) 2. Customer replied (needs attention) 3. Needs agent / update overdue (critical) 4. Other active tickets (on hold, pending) - SLA Visual Indicators: Red (overdue), orange (warning), green (normal) - Agent Workload: Filter by technician to see individual workload - PSA Integration: Click-through links to tickets in Freshservice/ConnectWise - Responsive Design: Mobile-friendly dashboard layout - Auto-Refresh: Polls Codex every 60 seconds for updates

Optional Services

Archive (Merged into Ledger)

Note: Archive functionality has been merged into Ledger as of November 2025. Access: Available at /ledger/archive/ Database: PostgreSQL (ledger_db)

Archive functionality provides immutable billing snapshot storage integrated directly into Ledger:

  • Billing Snapshots: Stores finalized bills as immutable records
  • Historical Lookup: Search past bills by company, year, and month
  • CSV Export: Download invoices for accounting and auditing
  • Automated Capture: Scheduled monthly snapshots of all company billing
  • Audit Trail: Complete history of accepted bills with timestamps

Key Features: - Permanent, unchangeable billing records - Integrated "Accept Bill & Archive" workflow - Automated monthly snapshot creation - Search by company, period, or invoice number - CSV invoice downloads - Job tracking for scheduled snapshots

API Endpoints (via Ledger): - /ledger/archive/api/snapshot/{invoice_number} - Retrieve specific snapshot - /ledger/archive/api/snapshot/{invoice_number}/csv - Download CSV invoice - /ledger/archive/api/snapshots/search - Search historical bills - /ledger/archive/api/scheduler/config - Configure automated snapshots

Service Dependencies

┌─────────────┐
│  Keycloak   │ (Authentication Server)
└──────┬──────┘
       │
       ├─────► Core (Authentication & Registry)
       │          │
       │          ├─────► Codex (Master Data)
       │          │          │
       │          │          ├─────► Ledger (Billing)
       │          │          │
       │          │          ├─────► KnowledgeTree (Knowledge)
       │          │          │
       │          │          └─────► Brainhair (AI Assistant)
       │          │
       │          └─────► Helm (Management)
       │
       └─────► Nexus (Gateway)
                  │
                  └─────► All Services (Proxied Access)

Service Communication

Services communicate through:

  1. HTTP APIs: JSON REST endpoints
  2. JWT Authentication: Bearer tokens for service-to-service calls
  3. Service Registry: Core maintains service locations
  4. Shared Database: Some services query Codex directly (read-only)

Adding New Services

See the Development Guide for details on creating custom services using the template.

Service Management

All services are managed through Helm:

# Via CLI
cd hivematrix-helm
source pyenv/bin/activate

# Check status
python cli.py status

# Start/stop individual services
python cli.py start codex
python cli.py stop ledger
python cli.py restart nexus

# Start all services
python cli.py start

# View logs
python logs_cli.py core --tail 100
python logs_cli.py brainhair --level ERROR
python logs_cli.py --tail 50  # All services

# Configuration management
python config_manager.py sync-all
python config_manager.py write-dotenv core

# Installation management
python install_manager.py install brainhair
python install_manager.py update-config

Or through the Helm web interface at http://localhost:5004

Production Features

All services implement these production-ready features:

  • Per-User Rate Limiting: JWT subject-based (prevents shared IP abuse)
  • Structured JSON Logging: Correlation IDs for distributed tracing
  • RFC 7807 Error Responses: Standardized machine-readable errors
  • Health Checks: Component-level monitoring at /health endpoints
  • OpenAPI/Swagger: Interactive API documentation at /docs endpoints
  • Security: Localhost binding (only Nexus binds to 0.0.0.0)