freshyo/edge_migration.md

# Edge Migration Plan: Node.js → Cloudflare Workers

## Overview

Migrating the backend from Node.js (Express, CommonJS) to Cloudflare Workers (V8 isolates, ESM, Web Standard APIs).

---

## BLOCKERS (Must fix, won't work at all)

### 1. Express.js — Complete Replacement Needed

**Affected files:**
- `apps/backend/index.ts`
- `apps/backend/src/main-router.ts`
- `apps/backend/src/v1-router.ts`
- All files in `apps/backend/src/apis/`
- All files in `apps/backend/src/uv-apis/`

**Problem:** Express uses Node.js `http` module internally — unavailable in Workers.

**Solution:** Replace with **Hono** (lightweight, Workers-native, similar middleware pattern) or use Cloudflare's `export default { fetch }` handler. Switch tRPC from `createExpressMiddleware` to `createFetchMiddleware` (Fetch adapter).

---

### 2. `node-postgres` (`pg`) Driver — TCP Sockets Unavailable

**Affected files:**
- `apps/backend/src/db/db_index.ts:1` — `drizzle-orm/node-postgres`

**Problem:** `node-postgres` uses TCP connections to Postgres. Workers have no TCP socket support.

**Solution:** Replace with `drizzle-orm/neon-http` (Neon serverless driver over HTTP) or use **Cloudflare Hyperdrive** (connection pooling proxy) with `@neondatabase/serverless` or fetch-based driver. Schema stays the same, only the driver changes.

---

### 3. Redis Client (`redis` npm package) — Persistent TCP + Pub/Sub Unavailable

**Affected files:**
- `apps/backend/src/lib/redis-client.ts` (full custom RedisClient class)
- `apps/backend/src/stores/product-store.ts`
- `apps/backend/src/stores/slot-store.ts`
- `apps/backend/src/stores/banner-store.ts`
- `apps/backend/src/stores/product-tag-store.ts`
- `apps/backend/src/stores/user-negativity-store.ts`
- `apps/backend/src/lib/const-store.ts`
- `apps/backend/src/lib/event-queue.ts`
- `apps/backend/src/lib/post-order-handler.ts`

**Problem:** The `redis` npm package uses Node.js `net`/`tls` modules. `subscribe()` / `publish()` require persistent TCP connections — fundamentally incompatible with Workers.

**Solution:** Replace with **Upstash Redis** (HTTP-based Redis, drop-in replacement for get/set/del operations) or **Cloudflare KV** (different API, eventual consistency). Pub/Sub must be rearchitected (see #17).

---

### 4. BullMQ — Depends on Node.js Events + Persistent Redis Connections

**Affected files:**
- `apps/backend/src/lib/notif-job.ts:1-41` — `Queue` and `Worker` classes

**Problem:** `Queue` and `Worker` classes depend on Node.js `EventEmitter` and persistent Redis TCP connections.

**Solution:** Replace with **Cloudflare Queues** (native message queue service) — different API entirely. Or use **Cloudflare Cron Triggers** + Upstash Redis for simpler job scheduling.

---

### 5. `node-cron` — No Background Process in Workers

**Affected files:**
- `apps/backend/src/lib/automatedJobs.ts`
- `apps/backend/src/jobs/jobs-index.ts`

**Problem:** Workers are request-driven — no long-running background processes. `cron.schedule()` is meaningless.

**Solution:** Replace with **Cloudflare Cron Triggers** (`wrangler.toml` crons config) — each cron invocation is a separate Worker invocation. Rewrite cron logic as fetch handler with `event.type === 'scheduled'`.

---

### 6. Multer — Express Middleware, Uses Node.js Streams

**Affected files:**
- `apps/backend/src/lib/upload-handler.ts` — multer config (10MB, memory storage)
- `apps/backend/src/main-router.ts:39` — complaint upload
- `apps/backend/src/uv-apis/uv-router.ts:9` — complaint upload
- `apps/backend/src/uv-apis/auth.router.ts:8-9` — profile image
- `apps/backend/src/apis/admin-apis/apis/product.router.ts:8-9` — product images
- `apps/backend/src/apis/admin-apis/apis/tag.router.ts:8,11` — tag image

**Problem:** Multer depends on Node.js streams and multipart parsing tied to Express.

**Solution:** Replace with native `Request.formData()` in Workers (built into the Fetch API) or use a Workers-compatible multipart parser like `@mjackson/multipart-parser`.

---

### 7. `fs` Module — No Filesystem in Workers

**Affected files:**
- `apps/backend/src/lib/signed-url-cache.ts:1,22-25,179,196,198` — `fs.existsSync()`, `fs.mkdirSync()`, `fs.writeFileSync()`, `fs.readFileSync()`
- `apps/backend/src/lib/disk-persisted-set.ts:1,13-14,18,28` — `fs.existsSync()`, `fs.writeFileSync()`, `fs.readFileSync()`

**Problem:** No filesystem in Workers. `fs.readFileSync`, `fs.writeFileSync`, `fs.existsSync`, `fs.mkdirSync` all unavailable.

**Solution:** Replace disk-persisted caches with **Cloudflare KV** or **Durable Objects** (for stateful storage).
- `signed-url-cache.ts` → KV with TTL
- `disk-persisted-set.ts` → KV or D1

---

### 8. Static File Serving (`express.static`, `res.sendFile`)

**Affected files:**
- `apps/backend/index.ts:134-173` — fallback UI serving, assets serving

**Problem:** No filesystem means no `express.static()` or `res.sendFile()`.

**Solution:** Deploy fallback UI as a separate **Cloudflare Pages** project. Serve assets from **R2** behind Workers. The fallback UI should not be bundled with the backend.

---

## MAJOR CHANGES (Significant rewrite required)

### 9. `process.env` — 47 Usages Across 10+ Files

**Affected files:**
- `apps/backend/src/lib/env-exporter.ts` (27 env vars exported)
- `apps/backend/index.ts`
- `apps/backend/src/db/db_index.ts`
- `apps/backend/src/middleware/auth.ts`
- `apps/backend/src/middleware/auth.middleware.ts`
- `apps/backend/src/middleware/staff-auth.ts`
- `apps/backend/src/trpc/trpc-index.ts`
- All files importing from `env-exporter.ts`

**Problem:** Workers expose env vars via the `Env` bindings object passed to `fetch(request, env)`, not `process.env`.

**Solution:** Every function that reads `process.env.*` needs refactoring to accept `env` as a parameter or use a shared context pattern. Create an `Env` type in `wrangler.toml` and thread it through the app.

---

### 10. `process.exit()` and Signal Handlers (`SIGTERM`, `SIGINT`)

**Affected files:**
- `apps/backend/src/lib/signed-url-cache.ts:254,260` — `process.exit()`
- `apps/backend/src/lib/disk-persisted-set.ts:71-72,76` — `process.exit()` and signal handlers
- `apps/backend/src/lib/notif-job.ts:163` — `process.on('SIGTERM', ...)`
- `apps/backend/src/db/porter.ts:120,124` — `process.exit()`

**Problem:** Workers don't have `process` object.

**Solution:** Remove all signal handlers and `process.exit()` calls. Graceful shutdown is handled by the platform.

---

### 11. `Buffer.from()` — 12 Usages

**Affected files:**
- `apps/backend/src/lib/cloud_cache.ts:27,52,77,102,127,152,259,266,273,280,287,298`

**Problem:** Workers don't have Node.js `Buffer`.

**Solution:** Replace with `new TextEncoder().encode()` or `Uint8Array`.

---

### 12. `crypto.createHmac()` — Node.js Crypto API

**Affected files:**
- `apps/backend/src/trpc/apis/user-apis/apis/payments.ts:8,72-75` — Razorpay signature verification

**Problem:** Node.js `crypto` module unavailable.

**Solution:** Replace with **Web Crypto API** (`crypto.subtle.importKey` + `crypto.subtle.sign`) — available natively in Workers but different async syntax.

---

### 13. `bcryptjs` — May Need WASM Alternative

**Affected files:**
- `apps/backend/src/uv-apis/auth.controller.ts:105,242` — `bcrypt.hash()`
- `apps/backend/src/trpc/apis/user-apis/apis/auth.ts:118,196,311` — `bcrypt.compare()`, `bcrypt.hash()`

**Problem:** bcryptjs uses Node.js `crypto.randomBytes` internally.

**Solution:** Works in Workers with latest bcryptjs, or replace with **`@noble/hashes`** (pure JS, no Node dependencies).

---

### 14. `jsonwebtoken` — Depends on Node.js Crypto

**Affected files:**
- `apps/backend/index.ts:16,81` — `jwt.verify()`
- `apps/backend/src/middleware/auth.ts:2,31` — `jwt.verify()`
- `apps/backend/src/middleware/auth.middleware.ts:2,32` — `jwt.verify()`
- `apps/backend/src/middleware/staff-auth.ts:2,25` — `jwt.verify()`
- `apps/backend/src/uv-apis/auth.controller.ts:3,53` — `jwt.sign()`
- `apps/backend/src/trpc/apis/user-apis/apis/auth.ts:4,53` — `jwt.sign()`
- `apps/backend/src/trpc/apis/admin-apis/apis/staff-user.ts:38` — `jwt.sign()`

**Problem:** The `jsonwebtoken` lib uses Node.js `crypto` internally.

**Solution:** Replace with **`jose`** (JWT library designed for Web Crypto API, Workers-compatible).

---

### 15. CommonJS → ESM Module System

**Affected files:**
- `apps/backend/tsconfig.json:29` — `"module": "commonjs"`
- `apps/backend/index.ts:135,136,167` — `__dirname` usage

**Problem:** Workers require ESM. `__dirname` not available in ESM.

**Solution:** Change `module` to `"ESNext"` or `"ES2022"`, `moduleResolution` to `"bundler"`. Remove all `__dirname` usage (static files handled differently, see #8).

---

### 16. AWS S3 (`@aws-sdk/client-s3`) — Replace with R2

**Affected files:**
- `apps/backend/src/lib/s3-client.ts` — S3Client, PutObjectCommand, DeleteObjectCommand, GetObjectCommand, getSignedUrl
- `apps/backend/src/lib/cloud_cache.ts` — Buffer.from() for S3 uploads
- `apps/backend/src/lib/s3-client.ts` — `generateSignedUrlFromS3Url()`

**Problem:** AWS SDK may have Node.js-specific dependencies.

**Solution:** R2 is S3-compatible — this is the easiest change. Update the S3Client endpoint to point to your R2 bucket. Or use the native `env.R2_BUCKET` binding for better performance. `@aws-sdk/s3-request-presigner` for upload URLs may need R2-specific handling.

---

## MODERATE CHANGES

### 17. Redis Pub/Sub for Order Notifications

**Affected files:**
- `apps/backend/src/lib/post-order-handler.ts` — subscribes to `orders:placed`, `orders:cancelled` channels

**Problem:** Pub/Sub requires persistent TCP connections.

**Solution:** Replace with **Durable Objects** with WebSocket broadcasting, or **Cloudflare Queues** for async event processing.

---

### 18. `expo-server-sdk` — May Not Work in Workers

**Affected files:**
- `apps/backend/src/lib/notif-job.ts`
- `apps/backend/src/lib/expo-service.ts`

**Problem:** SDK may use Node.js internals.

**Solution:** Check if the SDK uses Node.js internals; if so, replace with direct HTTP calls to Expo's push API via `fetch()`.

---

### 19. `razorpay` SDK — Check Node.js Dependencies

**Affected files:**
- `apps/backend/src/lib/payments-utils.ts` — `RazorpayPaymentService.createOrder()`, `initiateRefund()`, `fetchRefund()`

**Problem:** The Razorpay Node SDK may use `http`/`https` internally.

**Solution:** Replace with direct `fetch()` calls to Razorpay's REST API, or check if the SDK works with a polyfill.

---

### 20. `Error.captureStackTrace` — V8-Specific

**Affected files:**
- `apps/backend/src/lib/api-error.ts:12`

**Problem:** V8-specific API.

**Solution:** Available in Workers (V8 runtime), so this actually works. Verify during migration.

---

### 21. `process.uptime()` — Used in Health Checks

**Affected files:**
- `apps/backend/src/main-router.ts:18,26`

**Problem:** No `process` object in Workers.

**Solution:** Replace with a custom uptime tracker using `Date.now()` at module load.

---

### 22. `@turf/turf` — Check Bundle Size

**Affected files:**
- `apps/backend/src/trpc/apis/common-apis/common-trpc-index.ts:5` — `turf.booleanPointInPolygon()`

**Problem:** Workers have a **1MB compressed bundle limit** (free) or 10MB (paid). `@turf/turf` is a large library.

**Solution:** Import only `@turf/boolean-point-in-polygon` to reduce size. Or implement the point-in-polygon check manually using a lightweight algorithm.

---

## Infrastructure Changes

| Current | Workers Replacement |
|---------|-------------------|
| Express on port 4000 | `export default { fetch }` handler (Hono) |
| PostgreSQL via `pg` | Hyperdrive + Neon/serverless driver |
| Redis (`redis` npm) | Upstash Redis (HTTP) or Cloudflare KV |
| BullMQ | Cloudflare Queues |
| node-cron | Cloudflare Cron Triggers |
| AWS S3 | Cloudflare R2 |
| Disk filesystem | KV / D1 / R2 |
| Docker deployment | `wrangler deploy` |
| `dotenv/config` | `wrangler.toml` `[vars]` + Secrets |

---

## Migration Priority

### Phase 1 — Foundation
1. CommonJS → ESM (#15)
2. Replace `dotenv/config` with wrangler env bindings (#9)
3. Replace `jsonwebtoken` with `jose` (#14)
4. Replace Node.js `crypto.createHmac` with Web Crypto API (#12)

### Phase 2 — Data Layer
5. Replace `node-postgres` driver with Neon/HTTP driver (#2)
6. Replace Redis client with Upstash Redis (#3)
7. Replace `fs` cache with KV (#7)
8. Replace S3 with R2 (#16)

### Phase 3 — HTTP Layer
9. Replace Express with Hono (#1)
10. Replace Multer with native FormData (#6)
11. Move static files to Pages/R2 (#8)

### Phase 4 — Background Jobs
12. Replace BullMQ with Cloudflare Queues (#4)
13. Replace node-cron with Cron Triggers (#5)
14. Rearchitect pub/sub (#17)

### Phase 5 — Polish
15. Verify expo-server-sdk / razorpay SDK compatibility (#18, #19)
16. Optimize bundle size (#22)
17. Remove Dockerfile, update deployment pipeline