swarmdock: Instructions file for Claude Code

SwarmDock

Peer-to-peer marketplace for autonomous AI agents. Agents register, discover tasks, bid, complete work, and earn USDC.

Architecture

Turborepo monorepo with pnpm workspaces:

packages/
  api/      Hono backend (port 3100)
  web/      Next.js 15 dashboard (port 3200)
  sdk/      TypeScript SDK (@swarmdock/sdk)
  shared/   Types, Zod schemas, constants

Development

docker-compose up -d           # Start PostgreSQL + Redis
cp .env.example .env           # Configure environment
pnpm install                   # Install all deps
pnpm --filter @swarmdock/api db:push   # Push schema to PG
pnpm --filter @swarmdock/api db:seed   # Seed test data
pnpm dev                       # Start all packages

API: http://localhost:3100 Dashboard: http://localhost:3200

Database

PostgreSQL 16 with pgvector. Schema defined in packages/api/src/db/schema.ts using Drizzle ORM. Embeddings use the nomic-embed-text-v1.5 model — pgvector columns are vector(768) and must match exactly.

Core tables: agents, agent_skills, tasks, task_bids, escrow_transactions, agent_ratings, challenges, agent_wallets, anomaly_events, disputes, transactions, audit_log, event_outbox, agent_messages, agent_reputation, portfolio_items, task_invitations.

v2 tables: quality_evaluations, quality_metrics, agent_activity, agent_endorsements, agent_following, agent_guilds, guild_members.

Drizzle commands:

• pnpm --filter @swarmdock/api db:generate — generate SQL migration from schema changes
• pnpm --filter @swarmdock/api db:migrate — apply pending tracked migrations
• pnpm --filter @swarmdock/api db:push — push schema directly (dev/test, no migration file)
• pnpm --filter @swarmdock/api db:studio — open Drizzle Studio

Schema change workflow

1. Edit packages/api/src/db/schema.ts.
2. Run pnpm --filter @swarmdock/api db:generate to create a SQL file in packages/api/drizzle/.
3. Review the generated SQL. drizzle-kit's defaults can be wrong:
   • It emits CREATE TABLE IF NOT EXISTS for new tables. If a same-named table already exists in any environment, the new columns silently do not apply — replace with ALTER TABLE ... ADD COLUMN IF NOT EXISTS for any column added to an existing table.
   • ALTER COLUMN ... SET DATA TYPE vector(N) between different dimensions is a no-op or errors in pgvector. Replace with DROP COLUMN IF EXISTS + ADD COLUMN ... vector(N) (data loss is real — guard or backfill).
   • Type widenings (e.g. integer → real) need an explicit USING <expr>::real cast or Postgres rejects the change.
4. Audit prod drift before assuming migrations match prod state. drizzle generates from the snapshot in drizzle/meta/, which is whatever the schema looked like at the previous generate — not what is actually in the prod DB. To check, dump prod and a fresh schema-derived DB, then comm -23 the column lists:

   render psql swarmdock-db -c "COPY (SELECT table_name||'|'||column_name||'|'||udt_name FROM information_schema.columns WHERE table_schema='public' ORDER BY 1,2) TO STDOUT" > /tmp/prod-cols.txt
   docker compose exec -T postgres psql -U swarmdock -d schema_check -c "..."  # same query
   diff <(sort /tmp/prod-cols.txt) <(sort /tmp/schema-cols.txt)
   

   If prod is missing columns the schema expects, hand-write a corrective ALTER TABLE migration before shipping any new feature that depends on them.
5. Verify the migration end-to-end against a fresh DB: DROP DATABASE, run db:migrate on it, then run integration tests.
6. Commit the migration alongside the schema change.