cf-worker-restructuring

CF Worker Restructuring

Overview

Cloudflare Workers monoliths (a single worker.ts handling all routes) inevitably grow beyond maintainability. This skill provides a repeatable process for restructuring them into controller-based architecture: a thin router dispatching to per-domain controller modules.

The process emphasizes verification at every step via live wrangler dev and understanding the full dependency graph before touching any code.

When to Use

• worker.ts exceeds 400 lines with inline route handlers
• Multiple API domains (auth, analysis, history, reports) coexist in one file
• Shared constants/data (천간/지지/오행) are duplicated across frontend and backend
• Dead files accumulate (saju-data.js, ganji.js, orphaned src/api.ts)
• Frontend computes data that the backend should pre-calculate

Do NOT use for:

• Simple routing changes (use patch directly)
• Adding new routes to an already-clean structure
• UI-only refactoring

Step 1 — Map Current State

Before any code changes, build a complete map:

# All routes in worker.ts
grep -n "url.pathname ===\|url.pathname.startsWith" worker.ts

# All controller exports (if splitting)
for f in src/controllers/*.ts; do
  echo "$(basename $f): $(grep "^export async function" $f | sed 's/.*function //;s/(.*//' | tr '\n' ' ')"
done

# All env vars
grep -n "env\\." worker.ts | grep -o "env\\.[A-Z_]*" | sort -u

Key principle: Understand the full dependency graph before making any changes. The user will correct you if you miss something — capture those corrections.

⚠️ Workflow rule: Systematic inventory before fix. When something fails (e.g., a timeout, a missing dependency), do NOT propose a piecemeal workaround ("change the order so it uses X instead"). Instead, first find ALL components that share the same pattern, understand their purpose and intent, then design a unified fix. The user explicitly corrected this: "단편적인 해결 방안 말고, llm을 호출하는 애들을 찾아서 그 목적과 의도를 파악하고 해결 방안을 찾아야지."