# freepeak/cortex architecture

> Architecture diagram of the GitHub repository freepeak/cortex, 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/freepeak/cortex
- Repository: https://github.com/freepeak/cortex

## Overview

##### Project Type & Purpose
- Cortex is a server framework that adheres to the Model Context Protocol (MCP). It allows developers to build servers that expose tools, resources, and providers while supporting various transports (STDIO, HTTP/SSE, Multi-Protocol).
- The README makes it clear that the system is meant to help create context-aware servers for LLM interactions, with built-in support for logging, error handling, and plugin extensions.

##### Identifying Main Components
- Core Server Logic: Represented by the MCP server creation and lifecycle (using pkg/server, internal/usecases, and internal/infrastructure/server).
- Tools & Providers: Modules for defining and managing “tools” (pkg/tools) and “providers” (pkg/plugin) that encapsulate functionality.
- Domain Models & Use Cases: The “domain” package holds protocol messages, JSON-RPC models, errors, and notifications. The “usecases” package contains business logic for handling server interactions.
- Infrastructure: Contains sub-systems such as logging (internal/infrastructure/logging) and server utilities (internal/builder).
- Interfaces/Transports: There are multiple transport interfaces:
- STDIO interface (internal/interfaces/stdio)
- REST-like (internal/interfaces/rest)
- And examples for SSE and Multi-Protocol servers.
- Plugin System: For extending the server’s capabilities (pkg/plugin).
- Build & Testing Tools: The Makefile, go.mod/go.sum, test scripts, and CI-related configuration files show the structure for building and testing the project.

##### Architectural Patterns & Design Principles
- Layered Architecture/Clean Architecture: Separation between the domain (protocol definitions, errors, types), application logic (usecases), and infrastructure (logging, server implementation).
- Plugin / Provider Pattern: To allow dynamic extension of server capabilities.
- Separation of Transport Layers: Multiple interface types (STDIO, HTTP/SSE) are clearly abstracted into different interface folders.
- Builder Pattern: The internal/builder and pkg/builder packages build up server or tool objects in a modular fashion.

##### Components & Relationships to Highlight
a. MCP Server Core:
- Main entry point (e.g., cmd/main or examples that call server.NewMCPServer).
- Lifecycle management (initialization, message routing, shutdown).
- Should include details about using multiple protocols.
b. Tools & Providers:
- How tools are defined (via pkg/tools) and attached to the server.
- Plugin system for providers (pkg/plugin) that registers groups of tools.
c. Domain Layer:
- Interactions with domain models (protocol messages, JSON-RPC structure, error handling).
d. Infrastructure Components:
- Logging (internal/infrastructure/logging), server builders (internal/builder), and SSE connection management.
e. Interfaces / Transports:
- STDIO interface: Highlight the importance of directing logging to stderr.
- HTTP/SSE interface: For real-time server communication.
- Multi-Protocol support: Show how these might be concurrently running.
f. External Dependencies: Indicate how the project ties into external specifications (MCP spec URL) and dependency management (go.mod).

##### Final Checklist
- Clearly annotated components (e.g., "MCP Server Core", "Tool Management (pkg/tools)", "Provider Plugin System (pkg/plugin)", "Domain Models (internal/domain)", etc.).
- Notes or callouts indicating the use of Best Practices (clean architecture, layered separation, builder patterns, plugin extensibility).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces / Transports
    subgraph "Interfaces/Transports"
        STDIO["STDIO Interface (internal/interfaces/stdio)"]:::interface
        REST["REST-like Interface (internal/interfaces/rest)"]:::interface
    end

    %% MCP Server Core
    subgraph "MCP Server Core"
        SERVER["Server Logic (pkg/server)"]:::core
        LIFECYCLE["Lifecycle/Use Cases (internal/usecases/server)"]:::core
        INFRA_SERVER["Server Infrastructure (internal/infrastructure/server)"]:::core
    end

    %% Domain Models & Business Logic
    subgraph "Domain Models & Business Logic"
        DOMAIN["Domain Models (internal/domain)"]:::domain
    end

    %% Tools & Providers
    subgraph "Tools & Providers"
        TOOLS["Tools Module (pkg/tools)"]:::tools
        PLUGIN["Provider Plugin System (pkg/plugin)"]:::tools
        PROVIDER_EX["Provider Examples (examples/providers)"]:::tools
    end

    %% Infrastructure & Builders
    subgraph "Infrastructure & Builders"
        LOGGING["Logging (internal/infrastructure/logging)"]:::infra
        INTERNAL_BUILDER["Internal Builder (internal/builder/serverbuilder)"]:::infra
        PUBLIC_BUILDER["Public Builder (pkg/builder)"]:::infra
    end

    %% Connections from Interfaces to MCP Server Core
    STDIO -->|"sends request"| SERVER
    REST  -->|"sends request"| SERVER

    %% Internal Server Core flow
    SERVER -->|"triggers"| LIFECYCLE
    LIFECYCLE -->|"utilizes"| INFRA_SERVER

    %% MCP Server Core interactions with other components
    SERVER -->|"processes"| DOMAIN
    SERVER -->|"invokes"| TOOLS
    SERVER -->|"invokes"| PLUGIN
    SERVER -->|"logs via"| LOGGING
    SERVER -->|"builds using"| INTERNAL_BUILDER
    SERVER -->|"builds using"| PUBLIC_BUILDER

    %% Additional connection
    INFRA_SERVER -->|"integrates with"| LOGGING

    %% Click Events
    click SERVER "https://github.com/freepeak/cortex/blob/main/pkg/server/server.go"
    click LIFECYCLE "https://github.com/freepeak/cortex/blob/main/internal/usecases/server.go"
    click INFRA_SERVER "https://github.com/freepeak/cortex/tree/main/internal/infrastructure/server/"
    click STDIO "https://github.com/freepeak/cortex/tree/main/internal/interfaces/stdio/"
    click REST "https://github.com/freepeak/cortex/blob/main/internal/interfaces/rest/server.go"
    click DOMAIN "https://github.com/freepeak/cortex/tree/main/internal/domain/"
    click TOOLS "https://github.com/freepeak/cortex/blob/main/pkg/tools/helper.go"
    click PLUGIN "https://github.com/freepeak/cortex/tree/main/pkg/plugin/"
    click PROVIDER_EX "https://github.com/freepeak/cortex/tree/main/examples/providers/"
    click LOGGING "https://github.com/freepeak/cortex/tree/main/internal/infrastructure/logging/"
    click INTERNAL_BUILDER "https://github.com/freepeak/cortex/blob/main/internal/builder/serverbuilder.go"
    click PUBLIC_BUILDER "https://github.com/freepeak/cortex/tree/main/pkg/builder/"

    %% Styles
    classDef interface fill:#ffe6f2,stroke:#cc0066,stroke-width:2px;
    classDef core fill:#e6f2ff,stroke:#0066cc,stroke-width:2px;
    classDef domain fill:#e6ffe6,stroke:#00cc44,stroke-width:2px;
    classDef tools fill:#fff0e6,stroke:#ff6600,stroke-width:2px;
    classDef infra fill:#ffffe6,stroke:#cccc00,stroke-width:2px;
```
