chore: scaffold PYRE MVP monorepo (structure + docs)

pnpm + TypeScript workspace per design doc §13:
- apps/{web,api,worker} skeletons (Next.js 16, Fastify 5, BullMQ)
- packages/{core,solana,prometheus,db,config} (core has real types/DTOs;
  solana/prometheus are stubs)
- programs/pyre-core placeholder (future Anchor, v1.0)
- docs/: PYRE_MVP_DESIGN (canonical), ARCHITECTURE, SECURITY, TOKEN_CLASSIFICATION
- CLAUDE.md, README, .env.example (no private-key var by design)

Skeleton + docs only — no Solana/business logic yet. All workspaces typecheck clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/api/README.md

@@ -0,0 +1,38 @@
+# @pyre/api
+
+PYRE backend HTTP API. **Skeleton only** — endpoints exist as TODO stubs/route
+placeholders, NOT real implementations. No Solana transaction or scan/build
+logic is implemented yet (see [`CLAUDE.md`](../../CLAUDE.md), §14).
+
+Stack: Node.js + Fastify + TypeScript, with PostgreSQL (`@pyre/db`), Redis +
+BullMQ for queueing jobs handled by `@pyre/worker`.
+
+## Responsibilities (§13)
+
+Token scan coordination, classification helpers, route evaluation, AI generation
+orchestration, metadata preparation, receipt storage, Spawn record storage,
+public API, admin API.
+
+## Endpoints to implement (§14) — TODO
+
+- [ ] `POST /api/scan` — scan a wallet's token accounts; return summary + accounts.
+- [ ] `POST /api/build/close-empty` — build unsigned close-account tx for empty ATAs.
+- [ ] `POST /api/build/burn` — build unsigned burn tx for selected junk tokens.
+- [ ] `POST /api/receipt` — record/return a cleanup receipt for a confirmed tx.
+- [ ] `POST /api/prometheus/generate` — enqueue a Prometheus Spawn generation job.
+- [ ] Admin endpoints — review/approve/reject generated Spawn packages.
+
+Currently only `GET /health` is wired up.
+
+## Backend security rules (§16)
+
+Rate-limit scan endpoints, validate wallet pubkeys, validate token-account
+ownership, never trust client-submitted classifications (recompute server-side),
+log all transaction-build requests, protect admin endpoints, use env secrets only.
+
+## Scripts
+
+- `dev` — `tsx watch src/index.ts`
+- `build` — `tsc -p tsconfig.json`
+- `typecheck` — `tsc --noEmit`
+- `lint` / `test` — placeholders for now

apps/api/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@pyre/api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "PYRE backend HTTP API (Fastify) — scan, classify, build transaction, receipt, generation, admin endpoints.",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"TODO: lint\"",
+    "test": "echo \"TODO: tests\""
+  },
+  "dependencies": {
+    "@pyre/config": "workspace:*",
+    "@pyre/core": "workspace:*",
+    "@pyre/db": "workspace:*",
+    "@pyre/solana": "workspace:*",
+    "bullmq": "^5.34.0",
+    "fastify": "^5.2.0",
+    "ioredis": "^5.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}

apps/api/src/index.ts

@@ -0,0 +1,57 @@
+// PYRE backend API — SKELETON ONLY.
+//
+// Minimal Fastify bootstrap. Only `/health` is wired up. The §14 endpoints
+// below are intentionally NOT implemented — no scan/classify/build logic here.
+//
+// Trust rules (§16): never request private keys, never sign custodially,
+// always build an unsigned tx the client decodes + previews before signing,
+// validate wallet pubkeys, validate token-account ownership, never trust
+// client-submitted classifications (recompute server-side), log all tx-build
+// requests, rate-limit scan endpoints, protect admin endpoints.
+
+import Fastify from "fastify";
+
+const app = Fastify({ logger: true });
+
+app.get("/health", async () => {
+  return { status: "ok", service: "@pyre/api" };
+});
+
+// TODO (§14): implement the following routes as real, validated handlers.
+//   POST /api/scan
+//     in:  { wallet }
+//     out: { scanId, wallet, summary, accounts[] }
+//
+//   POST /api/build/close-empty
+//     in:  { wallet, accountAddresses[] }
+//     out: { transactionBase64, preview: { accountsToClose,
+//            estimatedRentReturnedLamports, rentDestination } }
+//
+//   POST /api/build/burn
+//     in:  { wallet, items[] }
+//     out: { transactionBase64, preview: { tokensToBurn, accountsPotentiallyClosable } }
+//
+//   POST /api/receipt
+//     in:  { wallet, txSignature, scanId }
+//     out: { receiptId, txSignature, rentReturnedLamports, closedAccounts,
+//            burnedTokens, skippedTokens }
+//
+//   POST /api/prometheus/generate   (enqueue BullMQ job for @pyre/worker)
+//     in:  { receiptId, chaos, operatorSeed? }
+//     out: { generationId, spawnName, ticker, lore, imagePrompt, metadata, riskFlags }
+//
+//   Admin endpoints — review/approve/reject Spawn generations (protected).
+
+const port = Number(process.env.PORT ?? 3001);
+const host = process.env.HOST ?? "0.0.0.0";
+
+// TODO: load + validate config via @pyre/config instead of reading process.env here.
+app
+  .listen({ port, host })
+  .then((address) => {
+    app.log.info(`@pyre/api listening on ${address}`);
+  })
+  .catch((err) => {
+    app.log.error(err);
+    process.exit(1);
+  });

apps/api/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}