HiveMatrix Architecture Documentation¶

Version 4.2 Last Updated: November 2025

Note: The architecture documentation has been split into three focused guides for easier navigation and AI processing. Each part can be read independently, though reading them in order is recommended for full understanding.

The HiveMatrix architecture is documented in three parts:

📘 Part 1: Core Architecture ¶

Essential reading for all developers and AI assistants

Covers the fundamental architecture patterns, authentication flows, and service communication that form the foundation of HiveMatrix.

Topics covered: - Core philosophy & design goals - Monolithic service pattern - End-to-end authentication flow (Keycloak → Nexus → Core) - Session management & logout flow - Service-to-service communication - Smart proxy composition (Nexus frontend) - Configuration management & auto-installation - AI instructions for building new services

Read this first to understand how HiveMatrix works.

🛠 Part 2: Development & Operations ¶

Development practices, security, and operational tools

Covers development workflows, security architecture, debugging tools, and operational best practices.

Topics covered: - Running the development environment - Keycloak auto-configuration - Backup & restore system - Development & debugging tools (logs_cli.py, create_test_token.py, security_audit.py) - Security architecture & firewall configuration - Design system & BEM classes - Database best practices - External system integration - Common patterns & service structure

Read this when setting up your development environment or implementing new features.

⚙️ Part 3: Service-Specific Implementation ¶

Deep dives into specialized services and production features

Covers service-specific implementations and advanced architectural patterns for key HiveMatrix services.

Topics covered: - Brainhair AI Assistant - Claude Code CLI integration, approval workflow, PHI/CJIS filtering, contract alignment, session management - Service-to-Service Communication Enhancements - Token caching (5-min TTL, 90% reduction in Core load) - Production Features - Redis session persistence, per-user rate limiting, structured JSON logging, RFC 7807 error responses, health checks, OpenAPI/Swagger docs - Centralized Logging (Helm) - PostgreSQL log aggregation, correlation IDs, 30-day retention - Billing Architecture (Ledger) - 5-step calculation flow, override system, Archive integration, bulk operations - Graph Database Pattern (KnowledgeTree) - Neo4j schema, hierarchical queries, full-text search - Version History - Complete changelog from v3.0 to v4.2

Read this when working on specific services or implementing production-ready features.

Why Split the Documentation?¶

The original 3,638-line ARCHITECTURE.md file was too large for efficient AI processing (exceeding the 25,000 token read limit). Splitting into three focused documents provides:

✅ AI-Friendly - Each part fits within AI tool read limits ✅ Easier Navigation - Find relevant information faster ✅ Logical Grouping - Related content stays together ✅ Progressive Learning - Read what you need, when you need it ✅ Better Maintainability - Update specific sections without touching entire doc

Reading Recommendations¶

For New Developers¶

Start with Core Architecture - Understand authentication, service communication, and basic patterns
Move to Development & Operations - Set up your environment and learn debugging tools
Reference Service-Specific as needed - Deep dive into services you're working on

For AI Assistants¶

Always read Core Architecture before making changes to any service
Reference Development & Operations for security rules, debugging, and best practices
Consult Service-Specific when working on Brainhair, Ledger, KnowledgeTree, or production features

For System Architects¶

Read all three parts to understand the complete system design
Start with Core, then Development, then Services
Version history in Part 3 shows architectural evolution

Quick Reference¶

Service Ports¶

Core: 5000 - Authentication & JWT management
Nexus: 443 - HTTPS gateway, only public-facing service
Helm: 5004 - Orchestration, logging, configuration
Beacon: 5001 - Ticket monitoring dashboard
Codex: 5010 - Master data (companies, contacts, assets, tickets)
KnowledgeTree: 5020 - Knowledge base (Neo4j graph database)
Ledger: 5030 - Billing calculation & invoicing (includes archive)
Brainhair: 5050 - AI assistant (Claude Code CLI)
Keycloak: 8080 - Authentication server (OAuth2/OIDC)

Key Architecture Points¶

All traffic goes through Nexus (the only public-facing service)
All services bind to localhost (127.0.0.1), except Nexus (0.0.0.0:443)
Services have NO CSS - Nexus injects global.css via proxy
Authentication: Keycloak → Nexus → Core (JWT exchange)
Services communicate via JWT-authenticated REST APIs
Configuration is centralized and auto-generated by Helm

Critical Rules¶

✅ Use ProxyFix (not custom middleware)
✅ Services bind to localhost (except Nexus)
✅ No CSS in services (BEM classes only)
✅ Read ARCHITECTURE docs before making changes
✅ Use service-to-service APIs (never direct database access)
✅ Include credentials: 'same-origin' in all fetch calls

Online Documentation¶

The complete HiveMatrix documentation is available online at:

https://skelhammer.github.io/hivematrix-docs/

Includes: - All three architecture parts - Service-specific guides - Installation instructions - API documentation - Troubleshooting guides

File Structure¶

hivematrix-docs/docs/
├── ARCHITECTURE.md                    # This index file
├── ARCHITECTURE-CORE.md               # Part 1: Core concepts (sections 1-7)
├── ARCHITECTURE-DEVELOPMENT.md        # Part 2: Development (sections 8-15)
├── ARCHITECTURE-SERVICES.md           # Part 3: Services (sections 16-22)
├── CLAUDE.md                          # AI assistant guidelines
├── services-overview.md               # Quick service reference
└── services/                          # Individual service docs
    ├── brainhair.md
    ├── codex.md
    ├── ledger.md
    └── knowledgetree.md

Version History¶

See ARCHITECTURE-SERVICES.md - Section 22 for complete version history from v3.0 to v4.2.

Latest: v4.2 - Comprehensive Service Documentation Integration (November 2025) - Complete Brainhair architecture rewrite - Service token caching (90% reduction in Core load) - Production features across all services - Centralized logging, billing architecture, graph database patterns

Continue reading: - Architecture - Core - Start here for fundamentals - Architecture - Development - Development workflow and tools - Architecture - Services - Service-specific deep dives