Fling Architecture

small software platform — describe it, deploy it, done

Overview
Fling lets users build and deploy personal tools through conversation with Claude. You describe what you want, Claude writes the code, and Fling handles everything else — bundling, deployment, databases, cron jobs, storage, secrets, and routing. No infrastructure knowledge required.
01
Describe
Talk to Claude
→
02
Build
Claude writes code
→
03
Push
fling push
→
04
Live
slug.flingit.run
Three Pillars
CLI
Command Line
The user-facing tool. Scaffolds projects, runs local dev, manages secrets, bundles code, and deploys to the platform.
  • fling init scaffold a project
  • fling dev local dev server
  • fling push deploy to production
  • fling secret manage secrets
  • fling db database operations
  • fling logs view production logs
Platform
Cloudflare Workers
Seven workers running on the edge. Handle auth, deployments, request routing, cron dispatch, email, and plugin integrations.
  • api auth, deploys, secrets
  • dispatch routes requests to apps
  • cron scheduled job dispatch
  • email-inbound receives email
  • discord / slack / email-send plugins
Runtime
Dual Runtime
Same API, two implementations. Users write code once — it runs on Node.js locally and on Cloudflare Workers in production.
  • app Hono HTTP framework
  • db SQLite / D1
  • cron croner / CF Triggers
  • secrets file / env bindings
  • storage filesystem / R2 + presigned URLs
  • onEmail inbound email handler
Request Flow
Every request to a Fling app passes through the Dispatch Worker, which resolves the target project by subdomain, custom domain, or path, checks usage limits, and forwards to the user's worker.
Incoming Request
Dispatch Worker
resolve project
Subdomain
slug.flingit.run
Custom Domain
myapp.com
Path Fallback
workers.dev/slug/…
check limits
Usage OK?
No
402 Payment Required
forward request
User Worker
fling_{user_id}_{project_name}
bind Cloudflare services
D1 Database
R2 Storage
Secrets
execute
User Code
Hono routes, cron handlers, email
Response
Routing Modes
Subdomain (slug.flingit.run) is primary. Custom domains use Cloudflare for SaaS. Path-based (workers.dev/slug/) is the fallback.
Internal Paths Blocked
Paths starting with /__ are reserved for platform internals (/__cron, /__email, /__plugin) and blocked from external access.
Dual Runtime
Users import from flingit and get the right implementation automatically. Local dev uses Node.js APIs; production uses Cloudflare Workers APIs. Zero code changes needed.
Local Development
fling dev starts a Node.js server. Uses local SQLite via better-sqlite3, secrets from .fling/secrets file, storage on the local filesystem, and croner for cron scheduling. Everything in .fling/data/.
Production
fling push bundles with esbuild, aliasing flingit to the worker runtime. Uses D1 for database, R2 for storage, env bindings for secrets, and Cloudflare Cron Triggers for scheduling. Same API surface.
the bridge
The esbuild alias trick — at bundle time, all import { app, db } from "flingit" statements are rewritten to import from the worker runtime instead. A generated entry shim calls __initEnv(env) with Cloudflare bindings before dynamically importing user code, so the runtime singletons are populated before user code runs.
Deploy Pipeline
fling push
01
Bundle
esbuild + entry shim
→
02
Upload
POST /project/deploy
→
03
Deploy
Wrangler to namespace
→
04
Sync
Secrets + crons + D1
→
05
Live
Globally distributed
Static Analysis
Cron schedules are extracted from the bundled code at deploy time and recorded in the cron_jobs table for the platform cron worker to dispatch.
Worker Naming
Each user worker is deployed to the dispatch namespace as fling_{user_id}_{project_name}, ensuring isolation between users.
Cloudflare Infrastructure
Fling runs entirely on Cloudflare. No servers, no containers — just edge compute with sub-millisecond cold starts.
Workers
Compute (V8 isolates)
D1
Database (SQLite)
R2
Object Storage (5GB)
KV
Usage limit cache
Cron Triggers
Scheduled jobs
Email Routing
Inbound email
for SaaS
Custom domains
for Platforms
Worker dispatch
Queues
Workflow execution
Workers for Platforms is the key enabling technology — it provides a dispatch namespace where each user's worker runs in isolation. The dispatch worker resolves the target and forwards the request using dispatcher.get(workerName). User workers get their own D1 database, R2 bucket, and secret bindings.
Deep Dive
Plugin System
How Discord, Slack, and Email integrations work — standalone plugin workers, OAuth flow, webhook dispatch, HMAC proxy auth, and the generic plugin framework.
→
Deep Dive
Integration Testing
The deploy → smoke test → teardown cycle — comprehensive verification steps, concurrent stress testing, diagnostics, and teardown on real Cloudflare infrastructure.
→
Deep Dive
Workflows
Durable execution engine — event sourcing, explicit continuations, dual-runtime architecture, D1EventStore, recovery, and bundler safety.
→