Architecture Overview

Architecture Overview

AgentMesh is engineered as a decoupled, multi-layered agent execution system following strict SOLID architecture guidelines.

---

System Layering

 +------------------------------------------------------------------------+
 |                         PYTHON DATA PLANE                              |
 |   LangGraph StateGraph / Agent Functions / LLM Calls (Groq, Gemini)    |
 +-----------------------------------+------------------------------------+
                                     | (Zero-Copy Pybind11 FFI)
 +-----------------------------------v------------------------------------+
 |                     AGENTMESH C++ CONTROL PLANE                        |
 |                                                                        |
 |  +------------------------+         +-------------------------------+  |
 |  |   WorkflowGraph        |         |     PriorityReadyQueue        |  |
 |  |  - Spec Graph (DAG)    |<------->|  - Priority DESC / FIFO Tie   |  |
 |  |  - Dynamic Trace Nodes |         |  - Lock-Free Synchronized     |  |
 |  +-----------+------------+         +---------------+---------------+  |
 |              |                                      |                  |
 |              v                                      v                  |
 |  +------------------------+         +-------------------------------+  |
 |  |  Scheduler (O(1) Engine|<------->|     AsyncEventDispatcher      |  |
 |  |  - Atomic In-Degrees   |         |  - LocalWorkerPool            |  |
 |  |  - Dynamic Unrolling   |         |  - Non-Blocking Timers        |  |
 |  +-----------+------------+         +-------------------------------+  |
 |              |                                                         |
 |              v                                                         |
 |  +------------------------------------------------------------------+  |
 |  |        State Repository (PostgresStateRepository / RAM)          |  |
 |  |        - Transactional Snapshots & Crash Recovery in <5ms        |  |
 |  +------------------------------------------------------------------+  |
 +------------------------------------------------------------------------+

---

Architectural Principles

1. Single Responsibility (SRP): Each subsystem (Graph, Scheduler, ReadyQueue, Persistence, Dispatcher) has a single clear purpose.
2. Open/Closed (OCP): New state backends or load balancing strategies can be added by implementing interfaces without modifying the engine.
3. Liskov Substitution (LSP): PostgresStateRepository and InMemoryStateRepository are 100% interchangeable via IStateRepository.
4. Interface Segregation (ISP): Interfaces are strictly partitioned (IReadyQueue, ITaskDispatcher, IStateRepository).
5. Dependency Inversion (DIP): The Scheduler depends solely on abstract interfaces, never on concrete network or database implementations.\n