# foreveryh/mentis architecture

> Architecture diagram of the GitHub repository foreveryh/mentis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/foreveryh/mentis
- Repository: https://github.com/foreveryh/mentis

## Overview

- Supervisor Module – Central component that assigns tasks, orchestrates coordination, and aggregates results. This is implemented in directories under core/agents/supervisor (both react-based and state-based variants) and also reflected in the examples.
- Specialized Agent Modules – Different smart agents are implemented for various specialties (coder, data analyst, designer, reporter, research) in core/agents/sub_agents as well as within other agent folders. Clearly indicate each family of agents and show them as distinct yet connected to the Supervisor.
- API Layer – There is an API module (in the “api” directory) that likely provides endpoints or gateway functionalities to interface with the system. Mark this as the service facade.
- Core Tools and Utilities – In core/tools and core/utils these modules offer support services (e.g., e2b_tool, firecrawl_tool) that are used throughout the system.
- LLM Integration – The core/llm directory manages language models and their configurations, forming a bridge between user queries or tasks and the underlying AI capabilities.
- Web Frontend – Under the “web” directory, a modern frontend (likely built using Next.js given file names like page.tsx, layout.tsx, etc.) provides the user interface for interacting with the multi-agent system. This should be depicted as a separate client component interacting (via API calls) with the backend services.
- Super Agents Section – The super_agents directory contains additional “deep research” functionality, including a reason_graph for advanced analysis. This can be shown as an extended module that queries existing agents or enhances the basic supervisor pattern.

##### Relationships and Data Flow
- Web Client (UI) → API Gateway (api directory) → Core Business Logic (Supervisor + Agent modules)
- Supervisor → Specialized Agents: Show control lines representing task assignment and handoff (using “handoff” modules).
- That the Supervisor gathers responses from specialized agents and then integrates the data. A feedback loop from agents back to Supervisor should be depicted.
- Also, illustrate that the system supports visualization of workflows (referenced in examples/graphs) which might be a separate module feeding into monitoring or debugging interfaces.

##### Architectural Patterns and Design Principles
- Modular Architecture: Emphasize that the system is organized into clearly separated modules (core logic, API, web UI, specialized agents, tools), which supports extensibility and maintenance.
- Supervisor Pattern: Underline that task delegation and result integration are managed via a central Supervisor pattern.
- Separation of Concerns: Distinguish between components handling business logic (core), presentation (web), and integration with external services (LLM, tools, API).
- Microservice-like Interaction: Although not necessarily microservices deployed separately, the clear boundaries (API, core, web) reflect a similar design mindset.

##### Relevant Technologies & Frameworks
- Python is the backbone for backend logic (files in core, super_agents, api).
- Next.js/React is used for the frontend (web directory).
- uv for dependency management and environment setup.
- LangGraph as the underlying multi-agent orchestration framework.
- Integration with external APIs (OpenAI, Tavily, FireCrawl, Jina).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend"
        WebUI["Web UI (Next.js)"]:::frontend
    end

    subgraph "Backend"
        APIGateway["API Gateway"]:::gateway
        subgraph "Supervisor Module"
            ReactSupervisor["Supervisor (React-based)"]:::business
            StateSupervisor["Supervisor (State-based)"]:::business
        end
        SubAgents["Specialized Agents (Coder,DataAnalyst,Designer,Reporter,Research)"]:::agent
        SuperAgents["Super Agents (Deep Research)"]:::superagent
    end

    subgraph "Support Services"
        LLMIntegration["LLM Manager"]:::support
        CoreTools["Core Tools"]:::support
        CoreUtils["Core Utilities"]:::support
        ExternalAPIs["External API Services"]:::external
    end

    %% Data Flow
    WebUI -->|"APIRequest"| APIGateway
    APIGateway -->|"ForwardTask"| ReactSupervisor
    APIGateway -->|"ForwardTask"| StateSupervisor
    ReactSupervisor -->|"DelegateTask"| SubAgents
    StateSupervisor -->|"DelegateTask"| SubAgents
    SubAgents -->|"ReturnResult"| ReactSupervisor
    SubAgents -->|"ReturnResult"| StateSupervisor
    ReactSupervisor -->|"AdvancedAnalysis"| SuperAgents
    StateSupervisor -->|"AdvancedAnalysis"| SuperAgents
    SuperAgents -->|"QueryInfo"| ReactSupervisor
    SuperAgents -->|"QueryInfo"| StateSupervisor

    ReactSupervisor <-->|"ModelQuery"| LLMIntegration
    StateSupervisor <-->|"ModelQuery"| LLMIntegration

    CoreUtils -->|"SupportFunctions"| CoreTools
    CoreTools -->|"ToolCalls"| ExternalAPIs
    LLMIntegration -->|"FetchModelData"| ExternalAPIs

    %% Click Events
    click WebUI "https://github.com/foreveryh/mentis/tree/main/web"
    click APIGateway "https://github.com/foreveryh/mentis/tree/main/api"
    click ReactSupervisor "https://github.com/foreveryh/mentis/tree/main/core/agents/react_based_supervisor"
    click StateSupervisor "https://github.com/foreveryh/mentis/tree/main/core/agents/state_based_supervisor"
    click SubAgents "https://github.com/foreveryh/mentis/tree/main/core/agents/sub_agents"
    click CoreTools "https://github.com/foreveryh/mentis/tree/main/core/tools"
    click CoreUtils "https://github.com/foreveryh/mentis/tree/main/core/utils"
    click LLMIntegration "https://github.com/foreveryh/mentis/tree/main/core/llm"
    click ExternalAPIs "https://github.com/foreveryh/mentis/tree/main/instructions"
    click SuperAgents "https://github.com/foreveryh/mentis/tree/main/super_agents/deep_research"

    %% Styles
    classDef frontend fill:#9ad1ff,stroke:#333,stroke-width:2px;
    classDef gateway fill:#ffdfba,stroke:#333,stroke-width:2px;
    classDef business fill:#c0e6a8,stroke:#333,stroke-width:2px;
    classDef agent fill:#f9e2ae,stroke:#333,stroke-width:2px;
    classDef support fill:#ffe0e0,stroke:#333,stroke-width:2px;
    classDef external fill:#d3f8e2,stroke:#333,stroke-width:2px;
    classDef superagent fill:#ffc0cb,stroke:#333,stroke-width:2px;
```
