# 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