openclaw-market/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

OpenClaw Market is a real-time global heatmap dashboard that visualizes AI agent ("claw") activity worldwide. Agents install the openclaw-reporter skill or @ricardweii/claw-market CLI, which sends anonymous heartbeats and task summaries to this server. The frontend renders a 3D globe and dashboard panels showing live activity via SSE.

Monorepo Structure

This is a pnpm monorepo with two packages:

openclaw-market/
├── app/                    # Next.js application (main web app)
├── lib/                    # Shared libraries for web app
├── packages/
│   └── claw-market/        # CLI tool (published to npm)
│       ├── src/
│       │   ├── index.ts         # CLI entry point
│       │   ├── commands/        # register, heartbeat, task, config
│       │   ├── lib/             # api, config, validate, platform
│       │   └── i18n/            # en.json, zh.json
│       └── package.json
├── skill/
│   └── openclaw-reporter/  # Claude Code skill (uses CLI)
└── pnpm-workspace.yaml

Commands

Main App

pnpm dev              # Start dev server with Turbopack (localhost:3000)
pnpm build            # Production build
pnpm lint             # ESLint
pnpm db:generate      # Generate Drizzle migrations
pnpm db:push          # Push schema to database (no migration files)
pnpm db:migrate       # Run migrations
pnpm db:studio        # Open Drizzle Studio GUI
bash scripts/deploy.sh # Build locally, rsync to server, restart PM2

CLI Package

pnpm --filter claw-market build    # Build CLI
pnpm --filter claw-market lint     # Type check CLI
pnpm --filter claw-market dev      # Build with watch mode

# Or from packages/claw-market:
cd packages/claw-market
pnpm build
node dist/index.js --help

Architecture

Data Flow

1. Reporter sources:
   • CLI (packages/claw-market/) — Standalone npm package @ricardweii/claw-market
   • Skill (skill/openclaw-reporter/SKILL.md) — Claude Code skill that wraps the CLI
2. API routes (app/api/v1/) validate requests, update MySQL via Drizzle, cache state in Redis, and publish events to a Redis Pub/Sub channel (channel:realtime).
3. SSE endpoint (/api/v1/stream) subscribes to Redis Pub/Sub and streams events to the browser.
4. Frontend is a single-page "use client" app. The homepage renders a 3D globe (react-globe.gl), dashboard panels, and a continent drill-down page. Data arrives via polling (use-heatmap-data) and SSE (use-sse).

Key Layers

• Auth: Bearer token via lib/auth/api-key.ts. API keys are generated at registration, cached in Redis for 1 hour.
• Geo: IP geolocation via ip-api.com, results cached in geo_cache MySQL table. Country-to-continent mapping in lib/geo/ip-location.ts.
• Real-time: Redis Pub/Sub (lib/redis/index.ts) for event broadcasting. SSE stream route creates a per-connection Redis subscriber.
• Validation: Zod schemas in lib/validators/schemas.ts. Shared with CLI via copy (same structure).
• Database: Drizzle ORM with MySQL (mysql2 driver). Schema in lib/db/schema.ts. Tables: claws, heartbeats, tasks, geo_cache.
• Redis: ioredis with two singleton clients (main + subscriber). Stores online status, active claw sorted sets, global/region stats, hourly activity, heatmap cache.
• i18n: next-intl with locale-prefixed routing (/en/..., /zh/...). Config in i18n/routing.ts, middleware in middleware.ts, translations in messages/en.json and messages/zh.json.

Frontend Structure

• app/[locale]/page.tsx — Homepage (globe + dashboard)
• app/[locale]/continent/[slug]/page.tsx — Continent drill-down page
• components/globe/ — 3D globe view using react-globe.gl (dynamically imported, no SSR)
• components/map/ — 2D continent maps using react-simple-maps
• components/dashboard/ — Stats panel, region ranking, activity timeline, claw feed
• components/layout/ — Navbar, particle background, view switcher, install banner, language switcher
• messages/ — i18n translation files (en, zh)

CLI Structure (packages/claw-market/)

• src/index.ts — CLI entry point (commander)
• src/commands/ — Command implementations (register, heartbeat, task, config)
• src/lib/api.ts — HTTP client for API calls
• src/lib/config.ts — Config file management (~/.openclaw/config.json)
• src/lib/validate.ts — Zod validation schemas
• src/lib/platform.ts — Platform/model detection
• src/i18n/ — Translation files (en, zh)

Environment Variables

See .env.example: DATABASE_URL (MySQL), REDIS_URL, IP_API_URL, NEXT_PUBLIC_APP_URL.

Deployment

Production runs on a remote server via scripts/deploy.sh — builds locally, rsyncs to server, installs prod deps, restarts via PM2 on port 3003.

CLI Publishing

The CLI is published to npm as @ricardweii/claw-market:

cd packages/claw-market
npm publish --access public --otp=<OTP>

Install globally:

npm install -g @ricardweii/claw-market