GoClaw/docs/project-analysis.md

GoClaw Project Analysis

Date: 2026-04-12

Project Overview

GoClaw — Distributed AI Agent orchestration platform ("Mission Control для вашего AI-агентского кластера"). Web-based Control Center for monitoring Docker Swarm clusters, managing AI agents, and interacting with an LLM-powered orchestrator.

Architecture

                    ┌─────────────────────────────────┐
                    │     goclaw-net (Overlay Network) │
                    └─────────────────────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              │                     │                     │
    ┌─────────▼──────┐   ┌──────────▼──────┐   ┌─────────▼──────┐
    │  Control Center │   │    Gateway       │   │   Agents        │
    │  (Web UI :3000) │   │  (Go + chi :18789) │  │  (Docker Svc)  │
    │  React + tRPC   │   │  Orchestrator    │   │  Go per-agent   │
    │  Express + Drizzle│  │  Tool Executor   │   │  HTTP :8001+   │
    └────────┬─────────┘   │  Docker Client   │   └─────────────────┘
             │             └──────┬───────────┘
             │                    │
    ┌────────▼─────────┐   ┌─────▼──────────────┐
    │   MySQL 8 / TiDB  │   │  Ollama Cloud API  │
    │   (Drizzle ORM)   │   │  (34+ LLM Models)  │
    └───────────────────┘   └─────────────────────┘

Tech Stack

Frontend

• React 19, Tailwind CSS 4, shadcn/ui, Framer Motion, Wouter, TanStack React Query, Recharts

Backend (Node.js)

• Express 4, tRPC 11, Drizzle ORM (MySQL), Zod, mysql2, jose (JWT), Axios, Vite, esbuild, Vitest

Backend (Go Gateway)

• chi/v5 (HTTP router), sqlx (MySQL), go-sql-driver/mysql

Database

• MySQL 8.0 / TiDB via Drizzle ORM

Infrastructure

• Docker Compose (local dev), Docker Swarm (production)

Services & Ports

Service	Container	Port	Status
MySQL DB	goclaw-db	3306	Healthy
Go Gateway	goclaw-gateway	18789	Healthy
Control Center	goclaw-control-center	3000	Healthy
Agent Worker	goclaw-agent-worker	8001 (dynamic)	Build only, deployed per-agent

Health Check Results

• Gateway: {"ollama":{"connected":true,"latencyMs":140},"service":"goclaw-gateway","status":"ok"}
• Control Center: {"status":"ok","uptime":21}

Database Schema (Key Tables)

• users — User accounts with OAuth, roles
• agents — AI agent configs (model, role, tools, system prompt)
• agentMetrics — Performance metrics
• agentHistory — Conversation history
• agentAccessControl — Per-tool access control
• toolDefinitions — Custom tool definitions
• browserSessions — Browser Agent sessions
• nodeMetrics — Docker container metrics
• tasks — Task tracking

Environment Variables (Core)

Variable	Default	Purpose
LLM_BASE_URL	https://ollama.com/v1	OpenAI-compatible LLM endpoint
LLM_API_KEY	(empty)	API key for LLM provider
DATABASE_URL	mysql://goclaw:goClawPass123@localhost:3306/goclaw	MySQL connection
JWT_SECRET	change-me-in-production	Session signing

Deployment Notes

• DB migration was applied successfully using drizzle-kit push
• 6 default agents seeded into the database
• OAUTH_SERVER_URL is not configured (optional for basic operation)
• Agent Worker containers are created dynamically when agents are deployed

Docker Compose Configuration

Project name: goclaw Network: goclaw-net (bridge) Volumes: mysql-data for persistence

Service Dependencies

• gateway depends on db (healthy)
• control-center depends on db (healthy) + gateway (healthy)

URL Endpoints

• Web UI: http://localhost:3000
• Gateway API: http://localhost:18789
• Health - Gateway: http://localhost:18789/health
• Health - Control Center: http://localhost:3000/api/health
• MySQL: localhost:3306