# esinecan/skynet-agent architecture

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

- Interactive diagram: https://gitdiagram.com/esinecan/skynet-agent
- Repository: https://github.com/esinecan/skynet-agent

## Overview

##### Project Type and Purpose
- This is a full-stack, monolithic AI assistant system (“Skynet Agent”) implemented in TypeScript/Node.js (backend) with a React/Vite/Tailwind frontend (“client”).
- Purpose: Expose an HTTP API and web GUI to drive an autonomous agent that integrates with Google Gemini (LLM), manages semantic memory (Milvus or in-memory), performs multi-step reasoning and self-reflection, and invokes external tools via the Model Context Protocol (MCP).

##### High-Level File Structure Analysis
- Top-level “src/” holds the backend:
- agent/ (workflow, intrinsic motivation, LLM client, self-reflection, schemas)
- memory/ (Milvus or in-memory storage, consolidation cron)
- mcp/ (external tool client manager)
- server/ (Express API, streaming, file uploads)
- db/ (session persistence)
- utils/ (config loader, logger, error handler, health checks)
- run.ts / index.ts (bootstrap + CLI args)
- “client/” holds the React GUI:
- App.tsx, components (ChatInterface, InputArea, MessageList, SessionList)
- Zustand store for streaming chat
- Vite/Tailwind configuration
- Deployment & config: Dockerfile, docker-compose.yml, .env + config.json, scripts (start.sh, start.bat)

##### README Insights on Architecture
- Backend initializes: loads .env, logger, error handlers → agent → Express server
- Agent pipeline: receives text → LLM calls (Gemini) → memory lookup/store → optional self-reflection or intrinsic tasks → response
- MCP: dynamically loads tool servers (e.g., Playwright, filesystem, CLI) → orchestrated via LangGraph workflow
- Memory consolidation: cron job summarizing stored memories
- Frontend: React SPA served statically by Express in production; dev uses proxy to backend

##### Diagramming the System
- Frontend Web UI (React + Vite + Tailwind)
- API Layer (Express.js server)
- Agent Core (workflow, motivation, reflection modules)
- LLM Service (Google Gemini API)
- Memory Store (Milvus vector DB or in-memory fallback + file-based sessions storage)
- MCP Clients (Playwright, filesystem, CLI, etc.)
- Scheduler (Memory Consolidation cron)
- Persistent Storage (local ./data directories for sessions & fallback memory)
- External Services (Milvus container, MCP servers)

1. User → Web UI (HTTP / SSE) → Express API
2. API → Agent Core (“processQuery(query, sessionId)”)
3. Agent Core → LLM Service (REST/gRPC calls to Gemini)
4. Agent Core ↔ Memory Store (vector search, insert, consolidation)
5. Agent Core → MCP Clients (spawn tool processes via MCP protocol)
6. Agent Core → API (stream back partial/full responses SSE or JSON)
7. Scheduler → Memory Store (trigger consolidation)
8. API → Persistent Storage (sessions CRUD)
9. Docker / docker-compose orchestrates backend, Milvus, and optional front-end container

c. Architectural Patterns & Principles:
- Layered separation: UI ↔ API ↔ Core Agent ↔ External dependencies
- Orchestrator pattern: LangGraph driving multi-step workflows
- Adapter pattern: llmClient wraps Gemini API; milvus.ts wraps vector DB
- Failover: in-memory fallback if Milvus unavailable
- Plugin/extensibility: dynamic MCP server loading

d. Key Technologies & Libraries:
- Backend: Node.js, TypeScript, Express, Multer, Zod, ts-node-dev, Jest
- Agent: Google Gemini embedding & generation, LangGraph workflow, intrinsicMotivation module, selfReflection module
- Memory: @zilliz/milvus2-sdk-node, in-memory consolidation
- MCP: @modelcontextprotocol clients
- Frontend: React18, TypeScript, Vite, Tailwind CSS, Zustand, React Markdown, SSE

##### Detail & Precision
- Every module from the file tree is represented at least at the component level.
- Dynamic flows: memory consolidation cron path, MCP reload API.
- Fallback paths (in-memory vs. Milvus).
- Important configuration sources (.env, config.json, VS Code settings).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Frontend Layer" 
        direction TB
        App["App.tsx"]:::frontend
        ChatInterface["ChatInterface.tsx"]:::frontend
        InputArea["InputArea.tsx"]:::frontend
        MessageList["MessageList.tsx"]:::frontend
        SessionList["SessionList.tsx"]:::frontend
        ChatStore["chatStore.ts"]:::frontend
        ViteConfig["vite.config.ts"]:::frontend
        TailwindConfig["tailwind.config.js"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        subgraph "API Layer"
            API["api.ts\n(Express.js)"]:::app
            IndexJS["index.ts"]:::app
            RunTS["run.ts"]:::app
        end

        subgraph "Agent Core"
            direction TB
            AgentIndex["index.ts"]:::app
            Workflow["workflow.ts"]:::app
            Intrinsic["intrinsicMotivation.ts"]:::app
            Reflection["selfReflection.ts"]:::app
            Schemas["appStateSchema.ts"]:::app
            LLMClient["llmClient.ts\n(Gemini Adapter)"]:::app
        end

        subgraph "Memory Module"
            direction TB
            MemoryIndex["index.ts\n(in-memory)"]:::data
            MilvusAdapter["milvus.ts"]:::data
            Consolidation["consolidation.ts\n(cron)"]:::app
        end

        MCPClient["client.ts\n(MCP)"]:::external
        SessionsDB["sessions.ts\n(ORM)"]:::data
        subgraph "Utilities"
            direction TB
            ConfigLoader["configLoader.ts"]:::app
            Logger["logger.ts"]:::app
            ErrorHandler["errorHandler.ts"]:::app
            Health["health.ts"]:::app
        end
    end

    %% Data & External Services Layer
    subgraph "Data & External Services"
        direction TB
        Gemini["Google Gemini API"]:::external
        MilvusContainer["Milvus Vector DB"]:::external
        FileStorage["File-based Sessions\n./data/"]:::data
        MCPServers["MCP Tool Servers"]:::external
        DockerCompose["Docker &\ndocker-compose"]:::external
    end

    %% Connections
    User(("User")):::external
    User -->|"HTTP GET/POST, SSE"| App
    App -->|"HTTP POST /api/query"| API
    API -->|"processQuery(query, sessionId)"| AgentIndex
    AgentIndex -->|"call LLM"| LLMClient
    LLMClient -->|"REST/gRPC"| Gemini
    AgentIndex -->|"vectorSearch()/insert()"| MemoryIndex
    AgentIndex -->|"vectorSearch()/insert()"| MilvusAdapter
    AgentIndex -->|"spawnTool()"| MCPClient
    MCPClient -->|"invoke"| MCPServers
    AgentIndex -->|"streamResponse SSE/JSON"| API
    API -->|"CRUD sessions"| SessionsDB
    Consolidation -->|"summarize()"| MemoryIndex
    Consolidation -->|"summarize()"| MilvusAdapter
    DockerCompose --> API
    DockerCompose --> MilvusContainer
    DockerCompose --> App

    %% Click Events
    click App "https://github.com/esinecan/skynet-agent/blob/main/client/src/App.tsx"
    click ChatInterface "https://github.com/esinecan/skynet-agent/blob/main/client/src/components/ChatInterface.tsx"
    click InputArea "https://github.com/esinecan/skynet-agent/blob/main/client/src/components/InputArea.tsx"
    click MessageList "https://github.com/esinecan/skynet-agent/blob/main/client/src/components/MessageList.tsx"
    click SessionList "https://github.com/esinecan/skynet-agent/blob/main/client/src/components/SessionList.tsx"
    click ChatStore "https://github.com/esinecan/skynet-agent/blob/main/client/src/stores/chatStore.ts"
    click ViteConfig "https://github.com/esinecan/skynet-agent/blob/main/client/vite.config.ts"
    click TailwindConfig "https://github.com/esinecan/skynet-agent/blob/main/client/tailwind.config.js"
    click API "https://github.com/esinecan/skynet-agent/blob/main/src/server/api.ts"
    click IndexJS "https://github.com/esinecan/skynet-agent/blob/main/src/index.ts"
    click RunTS "https://github.com/esinecan/skynet-agent/blob/main/src/run.ts"
    click AgentIndex "https://github.com/esinecan/skynet-agent/blob/main/src/agent/index.ts"
    click Workflow "https://github.com/esinecan/skynet-agent/blob/main/src/agent/workflow.ts"
    click Intrinsic "https://github.com/esinecan/skynet-agent/blob/main/src/agent/intrinsicMotivation.ts"
    click Reflection "https://github.com/esinecan/skynet-agent/blob/main/src/agent/selfReflection.ts"
    click Schemas "https://github.com/esinecan/skynet-agent/blob/main/src/agent/schemas/appStateSchema.ts"
    click LLMClient "https://github.com/esinecan/skynet-agent/blob/main/src/agent/llmClient.ts"
    click MemoryIndex "https://github.com/esinecan/skynet-agent/blob/main/src/memory/index.ts"
    click MilvusAdapter "https://github.com/esinecan/skynet-agent/blob/main/src/memory/milvus.ts"
    click Consolidation "https://github.com/esinecan/skynet-agent/blob/main/src/memory/consolidation.ts"
    click MCPClient "https://github.com/esinecan/skynet-agent/blob/main/src/mcp/client.ts"
    click SessionsDB "https://github.com/esinecan/skynet-agent/blob/main/src/db/sessions.ts"
    click ConfigLoader "https://github.com/esinecan/skynet-agent/blob/main/src/utils/configLoader.ts"
    click Logger "https://github.com/esinecan/skynet-agent/blob/main/src/utils/logger.ts"
    click ErrorHandler "https://github.com/esinecan/skynet-agent/blob/main/src/utils/errorHandler.ts"
    click Health "https://github.com/esinecan/skynet-agent/blob/main/src/utils/health.ts"

    %% Styles
    classDef frontend fill:#BFDBFE,stroke:#1E40AF,color:#1E3A8A
    classDef app fill:#BBF7D0,stroke:#166534,color:#14532D
    classDef data fill:#FED7AA,stroke:#C2410C,color:#7C2D12
    classDef external fill:#E9D5FF,stroke:#6B21A8,color:#4C1D95
```
