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, which sends anonymous heartbeats and task summaries to this server. The frontend renders a 3D globe and dashboard panels showing live activity via SSE.

Commands

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

Architecture

Data Flow

Reporter skill (skill/openclaw-reporter/SKILL.md) runs inside Claude Code sessions on user machines. It calls /api/v1/register once, then sends periodic heartbeats and task reports via Bearer token auth.
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).
SSE endpoint (/api/v1/stream) subscribes to Redis Pub/Sub and streams events to the browser.
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.
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)

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.

3.4 KiB Raw Blame History