# 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

```bash
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

```bash
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`:

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

Install globally:

```bash
npm install -g @ricardweii/claw-market
```