# techiral/omnimind architecture

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

- Interactive diagram: https://gitdiagram.com/techiral/omnimind
- Repository: https://github.com/techiral/omnimind

## Overview

##### Project Type and Purpose
- OmniMind is an open-source Python client library (SDK) for integrating with MCP (Model Context Protocol) servers, AI agents, workflows, and automations.
- It exposes a simple “OmniMind” interface to end-users, orchestrates connections to one or more MCP servers, and bundles a set of ready-to-use tools (Terminal, Fetch, Memory, Filesystem) plus pluggable custom tools.
- It also acts as a wrapper around external AI providers (e.g., Google Gemini) to deliver fast, reliable responses via MCP.

##### File-Structure Analysis
- Top-level:
- omnimind/             ← Python package with core modules
– client.py           ← main OmniMind class, orchestration logic
– config.py           ← server and tool configuration management
– utils.py            ← helper functions (logging, data conversions)
- examples/             ← sample scripts demonstrating usage
- docs/                 ← user/developer documentation
- tests/                ← unit tests for client and config
- setup.py, requirements.txt ← packaging and dependencies
- No frontend; it’s a library-only project.
- Presence of “add_server” hooks and “agent.run()” indicates extensibility points for custom MCP servers.
- CI workflows (.github/workflows) ensure build and test automation.

##### Core Components
a. User Application Layer
– Your Python code importing and instantiating OmniMind
– Example scripts under examples/
b. OmniMind Library
– OmniMind client (client.py)
– Configuration manager (config.py)
– Utils (utils.py)
– Tool Manager: internal registry of Terminal, Fetch, Memory, Filesystem
c. MCP Server(s)
– Custom servers added via agent.add_server()
d. External AI Provider
– Google Gemini (or other LLMs) as a remote service invoked over the MCP protocol
e. Optional Storage/Services
– Filesystem access tool
– Memory store (in-memory or external)
– Web fetch tool

##### Relationships and Interactions
- User Code → (calls) → OmniMind Client.run()
- OmniMind Client → (reads) → Configuration Manager (servers, tools)
- OmniMind Client → (negotiates connection) → MCP Server(s)
- MCP Server(s) → (dispatches requests) → Tools (Terminal, Fetch, Memory, Filesystem)
- MCP Server(s) → (forwards query) → External AI Provider (Google Gemini)
- External AI Provider → (responds) → MCP Server(s) → OmniMind Client → User Code

##### Important Architectural Patterns & Principles
- Plug-and-Play: All tools and servers are registered via a uniform interface.
- Separation of Concerns:
- Client handles orchestration
- Config handles parameterization
- Utils handle cross-cutting concerns
- Extensibility Points: agent.add_server(), custom tool registration
- CI/CD: Automated tests (tests/) and GitHub Actions ensure code quality

##### Detailed Component Breakdown (for maximum clarity)
- OmniMind Client
- initialize()
- add_server()
- run()
- Config Module
- load defaults
- override via examples/.env or code
- Utils
- logging
- request formatting
- MCP Server Interface
- Tool registry
- Request dispatcher
- Response aggregator
- Tools
- Terminal tool (shell exec)
- Fetch tool (HTTP client)
- Memory tool (state store)
- Filesystem tool (file I/O)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application Layer
    subgraph "User Application Layer"
        examples["examples/"]:::user
    end

    %% OmniMind Library
    subgraph "OmniMind Library" 
        client["OmniMind Client"]:::lib
        config["Configuration Manager"]:::lib
        utils["Utility Functions"]:::lib
        tools["Tool Manager"]:::lib
    end

    %% MCP Server Layer
    subgraph "MCP Server(s)"
        server["MCP Server Interface"]:::service
        subgraph "Built-in Tools"
            terminal["Terminal Tool"]:::service
            fetch["Fetch Tool"]:::service
            memory["Memory Tool"]:::service
            filesystem["Filesystem Tool"]:::service
        end
    end

    %% External AI Provider
    external["Google Gemini (External AI Provider)"]:::external

    %% CI/CD & Quality
    subgraph "CI/CD & Quality"
        ci["CI/CD Workflows"]:::service
        testClient["Unit Tests - Client"]:::service
        testConfig["Unit Tests - Config"]:::service
        docsAPI["API Reference Docs"]:::service
        tutCustom["Tutorial: Custom Server"]:::service
        tutGemini["Tutorial: Gemini Integration"]:::service
    end

    %% Relationships
    examples -->|"imports & calls"| client
    client -->|"reads settings"| config
    client -->|"uses helpers"| utils
    client -->|"manages tools"| tools
    client -->|"connects via MCP"| server
    server -->|"dispatches to"| terminal
    server -->|"dispatches to"| fetch
    server -->|"dispatches to"| memory
    server -->|"dispatches to"| filesystem
    server -->|"forwards query"| external
    external -->|"response via MCP"| client

    ci --> testClient
    ci --> testConfig
    ci --> docsAPI
    ci --> tutCustom
    ci --> tutGemini

    %% Click Events
    click examples "https://github.com/techiral/omnimind/tree/main/examples/"
    click client "https://github.com/techiral/omnimind/blob/main/omnimind/client.py"
    click config "https://github.com/techiral/omnimind/blob/main/omnimind/config.py"
    click utils "https://github.com/techiral/omnimind/blob/main/omnimind/utils.py"
    click ci "https://github.com/techiral/omnimind/blob/main/.github/workflows/welcome.yml"
    click testClient "https://github.com/techiral/omnimind/blob/main/tests/test_client.py"
    click testConfig "https://github.com/techiral/omnimind/blob/main/tests/test_config.py"
    click docsAPI "https://github.com/techiral/omnimind/tree/main/docs/api-reference/"
    click tutCustom "https://github.com/techiral/omnimind/blob/main/docs/source/tutorials/custom_server.rst"
    click tutGemini "https://github.com/techiral/omnimind/blob/main/docs/source/tutorials/gemini_integration.rst"

    %% Styles
    classDef lib fill:#ccf,stroke:#333,stroke-width:1px
    classDef user fill:#cfc,stroke:#333,stroke-width:1px
    classDef service fill:#ffc,stroke:#333,stroke-width:1px
    classDef external fill:#fcf,stroke:#333,stroke-width:1px
```
