🏗️ Marcus System Architecture Documentation#
Technical deep-dive documentation for all 55 systems powering Marcus’s AI agent coordination platform.
📋 System Overview#
Marcus is built on 55 interconnected systems that enable AI agents to collaborate autonomously. Each system is documented with implementation details, APIs, and integration patterns.
🧠 Core Intelligence Systems#
01 - Memory System#
Multi-tier cognitive memory (Working, Episodic, Semantic, Procedural) that enables learning and context retention across projects.
07 - AI Intelligence Engine#
Hybrid AI decision-making system combining multiple AI providers with context-aware prompt engineering.
17 - Learning Systems#
Continuous learning from project outcomes, pattern recognition, and performance optimization.
23 - Task Management Intelligence#
Intelligent task analysis, dependency inference, and automatic task breakdown.
27 - Recommendation Engine#
AI-powered recommendations for task assignment, technology choices, and workflow optimization.
44 - Enhanced Task Classifier#
Intelligent task categorization, priority scoring, and agent matching using ML and NLP.
🤖 Agent Coordination Systems#
21 - Agent Coordination#
Core agent lifecycle management, registration, assignment, and the work-loop protocol. (What earlier docs called “Communication Hub” is folded in here — there is no separate inter-agent message bus; coordination happens on the board.)
26 - Worker Support#
Tools and utilities that help AI agents work more effectively with context and error recovery.
03 - Context & Dependency System#
Intelligent context sharing between agents and automatic dependency resolution.
📊 Project Management Systems#
16 - Project Management#
High-level project creation, tracking, and completion management.
04 - Kanban Integration#
Multi-provider Kanban board integration. SQLite (default, zero-setup) plus Planka, GitHub Projects, and Linear.
24 - Analysis Tools#
Project analytics, performance metrics, and insight generation.
54 - Hierarchical Task Decomposition#
AI-powered task breakdown into manageable subtasks with clear interfaces and shared conventions.
🔧 Development & Analysis Systems#
42 - Code Analysis System#
Repository analysis, language detection, complexity assessment, and security scanning for agent-generated code.
🔒 Security & Compliance Systems#
51 - Security Systems#
Comprehensive security framework including authentication, threat detection, and workspace isolation.
🗄️ Data & Storage Systems#
10 - Persistence Layer#
Data storage abstraction supporting multiple backends (SQLite, JSON, PostgreSQL).
32 - Core Models#
Data models for tasks, agents, projects, and system entities.
13 - Cost Tracking#
API usage monitoring and cost optimization across AI providers.
19 - NLP System#
Natural language processing for task analysis and context extraction.
✅ Quality & Testing Systems#
18 - Quality Assurance#
Automated quality checks, code review, and deployment validation.
30 - Testing Framework#
Comprehensive testing infrastructure for all Marcus components.
11 - Monitoring Systems#
Real-time system monitoring, health checks, and alerting.
29 - Detection Systems#
Anomaly detection, error pattern recognition, and preventive measures.
🏭 Infrastructure Systems#
08 - Error Framework#
Comprehensive error handling with automatic recovery and escalation.
09 - Event-Driven Architecture#
Publish/subscribe system for loose coupling and scalability.
06 - MCP Server#
Model Context Protocol server implementation for AI agent integration.
14 - Workspace Isolation#
Secure isolation between agents and projects.
15 - Service Registry#
Dynamic service discovery and health management.
⚙️ Operations Systems#
22 - Operational Modes#
Different operation modes (development, staging, production) with appropriate configurations.
28 - Configuration Management#
Dynamic configuration system with environment-based overrides.
31 - Resilience#
Fault tolerance, circuit breakers, and graceful degradation.
🎨 Visualization Systems#
05 - Visualization System#
Real-time dashboards and project visualization tools. The active visualization product is Cato, which reads board state directly.
02 - Logging System#
Comprehensive logging infrastructure with multiple output formats.
🔍 How to Use This Documentation#
For New Developers#
Start with Core Intelligence systems to understand how Marcus thinks
Review Agent Coordination to understand agent workflows
Check Infrastructure systems for integration patterns
For System Integration#
Review MCP Server (06) for API integration
Check Error Framework (08) for proper error handling
Study Configuration Management (28) for setup
For Extension Development#
Understand Event-Driven Architecture (09) for loose coupling
Review Service Registry (15) for service discovery
Check Testing Framework (30) for validation
For Operations#
Study Monitoring Systems (11) for observability
Review Resilience (31) for fault tolerance
Check Pipeline Systems (20) for deployment
🔗 System Interdependencies#
graph TD
A[01-Memory] --> B[07-AI Engine]
B --> C[17-Learning]
C --> D[27-Recommendations]
E[21-Agent Coord] --> F[26-Worker Support]
F --> G[03-Context System]
G --> H[12-Communication]
I[16-Project Mgmt] --> J[04-Kanban]
J --> K[24-Analysis]
K --> L[25-Reports]
M[08-Error Framework] --> N[09-Events]
N --> O[06-MCP Server]
O --> P[15-Service Registry]
📈 System Metrics#
55 Total Systems documented
6 Core Intelligence systems for AI decision-making and classification
4 Agent Coordination systems for workflow management
2 Development & Analysis systems for code quality and API integration
1 Security & Compliance system for comprehensive security
7 Project Management systems including workflow orchestration and task decomposition
5 Infrastructure systems for reliability and scalability
4 Quality & Testing systems for reliability
Rest: Data storage, operations, and visualization systems
🤝 Contributing to System Documentation#
When modifying systems:
Update the relevant system documentation
Update this README if adding/removing systems
Update interdependency diagrams if changing relationships
Add integration examples for new APIs
Document breaking changes clearly
💡 Implementation Notes#
All systems follow Event-Driven Architecture principles
Error Framework provides consistent error handling across systems
Configuration Management allows per-environment customization
Testing Framework ensures all systems maintain quality standards
MCP Server exposes unified API regardless of internal complexity
Each system is designed to be independently testable, scalable, and maintainable while contributing to Marcus’s overall AI agent coordination capabilities.