qr-for-agent-api: Instructions file for Claude Code

QR for Agent — Context for Claude

On arrival

Before starting any work, read the project status memory file to get up to speed on what's been done and what's pending: ~/.claude/projects/-Users-benjaminturc-Library-CloudStorage-GoogleDrive-benjamin-swel-fr-Mon-Drive-Claude-Code/memory/qr-for-agent-status.md

After pushing new features, update that same memory file: move completed items, add new TODOs, bump versions if applicable.

What is this project?

QR for Agent is a QR-as-a-Service API built for AI agents. It lets agents create, update, and track dynamic QR codes programmatically. The QR image never changes — but its destination URL can be retargeted at any time.

Live API: deployed on Railway (Docker-based) MCP package: qr-for-agent on npm (packages/mcp/) Marketing site: separate repo benswel/qr-for-agent-site, deployed on Cloudflare Pages at qrforagent.com

Architecture

src/
├── server.ts              # Entry point — starts Fastify on configured port
├── app.ts                 # App builder: CORS, Swagger, auth plugin, route registration
├── config/index.ts        # Env vars: PORT, HOST, BASE_URL, DATABASE_URL, SHORT_ID_LENGTH, ADMIN_SECRET
├── db/
│   ├── schema.ts          # Drizzle schema: api_keys, qr_codes, scan_events, webhooks, webhook_deliveries, conversion_events
│   ├── index.ts           # better-sqlite3 + drizzle-orm init (WAL mode)
│   └── migrate.ts         # Auto-migration on startup
├── shared/
│   ├── types.ts           # QrFormat, QrType (11 types), all *Data interfaces, PaginatedResponse, Plan, PLAN_LIMITS, Fastify augmentation
│   └── errors.ts          # Structured errors with code + hint (agent-friendly)
├── modules/
│   ├── auth/              # X-API-Key auth plugin + key management
│   ├── qr/                # CRUD routes, service, schemas, custom SVG renderer
│   ├── domain/            # Custom domain management (GET/PUT/DELETE /api/domain + DNS checker)
│   ├── conversions/       # Conversion tracking (pixel + API + webhook dispatch)
│   ├── redirect/          # GET /r/:shortId — public redirect + scan recording + webhook dispatch
│   ├── analytics/         # GET /api/analytics/:shortId — scan stats
│   ├── webhooks/          # Webhook CRUD + HMAC delivery + delivery logging
│   ├── stripe/            # Stripe Checkout, Customer Portal, webhook handler
│   ├── image/             # GET /i/:shortId — public QR image (cacheable)
│   └── well-known/        # /.well-known/ai-plugin.json + mcp.json
├── cli/                   # key:create, key:list scripts
packages/
└── mcp/                   # Standalone MCP server (published as qr-for-agent on npm)