Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Cloudflare Workers
Worker Configuration (backend/wrangler.toml)
name = "twiligent"
main = "server.ts"
compatibility_date = "2025-01-01"
[triggers]
crons = ["* * * * *", "*/5 * * * *", "0 0 * * *"]
name- the Worker name as deployed on Cloudflare; also determines the default URLmain- entry point file (backend/server.ts). Wrangler bundles it with esbuild, which strips the TypeScript types without checking them;npm run typecheckis the checkcompatibility_date- pins the Workers runtime API versioncrons- cron trigger schedules (seedocs/architecture/backend/CRON.md). The every minute trigger sends waiting comment replies and follow-ups; the five minute trigger publishes due posts on the quarter hour and checks the reply queue on its other runs; the daily trigger refreshes tokens and deletes old records. The Workers Free plan allows five cron triggers per account and this Worker uses three, so a self-hoster with other Workers should count the triggers on their account first. Each cron run counts as a Worker request: the every minute trigger adds 1,440 a day (about 1.4% of the Free plan's 100,000), the five minute one 288 and the daily one 1
Worker Export Format
The Worker exports two handlers:
export default {
fetch: app.fetch, // handles HTTP requests (the Hono app from backend/app.ts)
async scheduled(event: ScheduledController, env: Env, ctx: ExecutionContext) { // handles cron triggers
ctx.waitUntil(runScheduledJob(event.cron, env, event.scheduledTime));
},
} satisfies ExportedHandler<Env>;
event.cron is the cron expression that fired, event.scheduledTime the minute it was due for, env holds the Worker secrets and variables, and ctx.waitUntil(promise) keeps the Worker alive for the job. runScheduledJob() in backend/jobs/scheduled.ts picks the job for the expression; see docs/architecture/backend/CRON.md.
ScheduledController, ExecutionContext and ExportedHandler come from @cloudflare/workers-types, which backend/tsconfig.json loads as its only ambient types.
Environment Bindings (Secrets)
All secrets are set via npx wrangler secret put <NAME>, run from backend/. They are available at runtime as env.NAME or c.env.NAME, typed by the Env interface in backend/types/env.ts. The three Supabase values are declared as string; the rest are optional (?: string), so code that reads them handles the missing case. Application code reads them through readConfig(env) in backend/lib/config.ts, which trims stray whitespace and byte order marks; a request that needs a missing optional value fails with 503 (NOT_CONFIGURED).
| Secret | Required | Purpose |
|---|---|---|
SUPABASE_URL |
Yes | Supabase project URL |
SUPABASE_SERVICE_KEY |
Yes | Service-role key - bypasses RLS, all DB operations |
SUPABASE_ANON_KEY |
Yes | Anon key - used only for JWT verification in requireAuth |
YOUTUBE_API_KEY |
Yes | Shared YouTube Data API v3 key (all users share quota) |
INSTAGRAM_APP_ID |
Yes | Meta/Facebook App ID for OAuth |
INSTAGRAM_APP_SECRET |
Yes | Used for OAuth token exchange + HMAC state signing |
CLOUDINARY_CLOUD_NAME |
Yes | Cloudinary cloud name |
CLOUDINARY_UPLOAD_PRESET |
Yes | Unsigned upload preset for direct browser uploads |
BACKEND_URL |
Yes | This Worker's public URL (for OAuth callback construction) |
FRONTEND_URL |
Yes | Frontend URL: the browser origin CORS allows, and the post-OAuth redirect back to the SPA |
ALLOWED_ORIGINS |
Optional | Comma-separated extra browser origins CORS allows besides FRONTEND_URL, such as a second domain (https://a.example.com,https://b.example.com). Set it with wrangler secret put like the others, so the next wrangler deploy keeps it (a plain variable added in the dashboard can be replaced on deploy) |
UPSTASH_REDIS_REST_URL |
Optional | Upstash Redis endpoint; caching disabled if absent |
UPSTASH_REDIS_REST_TOKEN |
Optional | Upstash auth token |
SEND_EMAIL_HOOK_SECRET |
Optional | The Send Email hook secret from Supabase (v1,whsec_...); verifies that POST /api/auth/email-hook was called by your Supabase Auth. Without it the hook answers 503 |
RESEND_API_KEY |
Optional | Resend API key with sending access; sends the auth emails (verification codes) |
EMAIL_FROM |
Optional | Sender of the auth emails on a domain verified in Resend, such as Twiligent <[email protected]> |
EMAIL_DAILY_LIMIT |
Optional | Auth emails a day across all users (each code sign-in is one) before the sign-in page pauses email codes and points to Google or a password; defaults to 100, Resend's free daily quota |
INSTAGRAM_WEBHOOK_VERIFY_TOKEN |
Optional | The Verify Token typed into the Meta dashboard's Instagram webhook settings; GET /api/webhooks/instagram answers Meta's check only with it. Without it, and INSTAGRAM_APP_SECRET, no comment reaches the Worker and the Instagram automation page says so |
CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET |
Optional | The Cloudinary account's API key and secret (Settings, API Keys). Only for deleting files through the Claude delete_media tool; without them a delete removes Twiligent's record and says the file stays on Cloudinary. Never sent to the browser |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET |
Optional | The Google Cloud Web application OAuth client for YouTube publishing (redirect URI <BACKEND_URL>/api/auth/youtube/callback). With TOKEN_ENCRYPTION_KEY they turn YouTube publishing on; see docs/platform-v2/YOUTUBE_INTEGRATION.md |
TOKEN_ENCRYPTION_KEY |
Optional | At least 32 random characters (openssl rand -base64 48). Keys derived from it sign the MCP confirmation tokens and seal the stored Google tokens (AES-GCM). Without it the Claude tools that publish or delete refuse to run and YouTube publishing stays off. Changing it voids confirmations in flight and makes every stored Google token unreadable, so people connect YouTube again |
MCP_OAUTH_ENABLED |
Optional | true once Supabase Auth's OAuth server is turned on with the authorization path /oauth/consent; the MCP endpoint then publishes its protected resource metadata, so Claude on the web, desktop and mobile can connect. Access tokens work without it |
META_APP_SECRET |
Optional | The Meta app's own secret (App settings, Basic). Webhook signatures are checked against INSTAGRAM_APP_SECRET and, when this is set, against it too |
AUTOMATION_PAUSED |
Optional | true holds every comment-to-DM reply on the instance; comments are still stored and matched |
AUTOMATION_ACCOUNT_HOURLY_LIMIT |
Optional | Private replies an hour per Instagram account; default 200, at most 750 (Instagram's limit) |
AUTOMATION_USER_HOURLY_LIMIT |
Optional | Private replies an hour across one member's accounts; default 500 |
AUTOMATION_GLOBAL_HOURLY_LIMIT |
Optional | Private replies an hour across the instance; default 1000 |
AUTOMATION_RECIPIENT_DAILY_LIMIT |
Optional | Private replies a day one person can get from one account; default 3 |
AUTOMATION_PUBLIC_ACCOUNT_HOURLY_LIMIT |
Optional | Public replies under comments an hour per Instagram account; default 60, at most 200. Meta publishes no limit for comment replies but blocks accounts that comment like a bot, so the pace stays human |
AUTOMATION_BATCH_SIZE |
Optional | Replies sent by one webhook request or one dispatch run, for each kind of reply; default 10, at most 15 (each costs three of the free plan's 50 subrequests) |
The automation values are plain settings, not secrets, but setting them with wrangler secret put keeps them across deploys like the rest. A missing or invalid value falls back to its default.
Setting secrets
cd backend
npx wrangler secret put SUPABASE_URL
npx wrangler secret put SUPABASE_SERVICE_KEY
# (paste value when prompted - no echo)
Local development (.dev.vars)
Create backend/.dev.vars (gitignored) with the same keys:
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
YOUTUBE_API_KEY=AIzaSy...
INSTAGRAM_APP_ID=123456789
INSTAGRAM_APP_SECRET=abc123...
CLOUDINARY_CLOUD_NAME=mycloud
CLOUDINARY_UPLOAD_PRESET=ml_default
BACKEND_URL=http://localhost:8787
FRONTEND_URL=http://localhost:5173
# ALLOWED_ORIGINS=https://another-domain.example.com
UPSTASH_REDIS_REST_URL=https://...
UPSTASH_REDIS_REST_TOKEN=...
# only to test the Send Email hook locally; Supabase cannot reach localhost, so sign request bodies yourself
# SEND_EMAIL_HOOK_SECRET=v1,whsec_...
# RESEND_API_KEY=re_...
# EMAIL_FROM=Twiligent <[email protected]>
# only to test the Instagram webhook locally; Meta cannot reach localhost, so sign request bodies yourself
# INSTAGRAM_WEBHOOK_VERIFY_TOKEN=a-long-random-string
# AUTOMATION_PAUSED=true
# signs the MCP confirmation tokens; any 32 or more random characters
# TOKEN_ENCRYPTION_KEY=...
Run locally from the repository root: npm run dev:backend (Worker only, port 8787) or npm run dev (Worker and Vite together). Both run wrangler dev in backend/, which reloads on save.
CORS origins
The API answers browsers only on FRONTEND_URL and the origins in ALLOWED_ORIGINS; a browser on any other origin is blocked. A Worker served from localhost or 127.0.0.1 also allows the Vite dev server (http://localhost:5173 and http://127.0.0.1:5173), so local development needs no extra setting. Requests without an Origin header (curl, the GitHub Actions scheduler) are not affected. See docs/architecture/backend/MIDDLEWARE.md.
Worker Constraints
These are hard constraints imposed by the Cloudflare Workers runtime. Violating them causes runtime errors:
No Node.js APIs. No
fs,Buffer,path,process.env(usec.env),require(). Everything must be ESMimport.backend/tsconfig.jsondoes not load the Node types, sonpm run typecheckflags these in Worker source.No binary file handling. The Worker cannot efficiently stream large binary files. Never add routes that accept file uploads - Cloudinary handles that directly from the browser.
No persistent state between requests. The Worker isolate may be a fresh instance on every request. Do not rely on module-level variables to persist state across requests. All state must come from Supabase, Redis, or Worker KV. (The cache cooldown and the rate limiter's memory fallback keep per-isolate state on purpose, as a best-effort optimization that is safe to lose.)
CPU time limit. On the Workers Free plan each invocation gets 10 ms of CPU time (Workers Paid: 30 seconds by default, up to 5 minutes). Time waiting on
fetchdoes not count, so I/O-bound work fits; long synchronous work is killed. Use async/await for all I/O.Subrequests. On the Workers Free plan an invocation can make 50 subrequests (each
fetch, including Supabase and Redis calls); Workers Paid allows 10,000. A webhook request, a dispatch run, a reconcile run and a publishing run each count separately.AUTOMATION_BATCH_SIZEis capped at 15 for this reason, and a fetch the runtime refuses at the cap is recorded as not sent rather than as an unknown outcome.ctx.waitUntil()in cron handlers and after responses. Cron handlers must usectx.waitUntil(promise)for async work. Without it, the Worker may terminate before the work completes. After an HTTP response,waitUntilkeeps the Worker running for at most 30 seconds;inBackground()incontrollers/http.tsgives such work its own 25 second deadline.Bundle size. The Worker bundle must be a single ESM file (Wrangler handles bundling). Avoid large dependencies. Type-only imports, including everything in
shared/types/, add nothing to the bundle.
Adding a New Worker Secret
- Declare it in the
Envinterface inbackend/types/env.ts(NEW_SECRET_NAME?: stringunless the Worker cannot run without it), and read it intoAppConfiginbackend/lib/config.tswithcleanSecret() - Set via
npx wrangler secret put NEW_SECRET_NAMEfrombackend/ - Add to
backend/.env.examplewith a placeholder value - Add to
backend/.dev.varslocally - Set as a GitHub secret if needed by deploy workflow
- Update
docs/architecture/cloudflare/WORKERS.md(this file) - Append to
DECISIONS.mdif it represents an architectural dependency