heygo/README.md

Heygo

Heygo is an independent Cloudflare React + Workers scaffold for a future shortlinks app.

This repository lives at /home/ai-bot/code/heygo and is intentionally separate from the old Linux/Django Links repository. The old Links repository under /home/ai-bot/code/links is read-only reference material only and must not be modified by this project.

Local development

npm install
npm run dev
npm run dev:worker

• npm run dev starts the Vite React SPA dev server.
• npm run dev:worker starts the Cloudflare Worker locally with Wrangler.

Verification

npm run build
npm test

• npm run build type-checks the TypeScript project and builds the React SPA into dist/client for Workers Assets.
• npm test runs Vitest tests against the Worker API handler.

Deployment

Heygo ships as a single Cloudflare Worker fronted by two custom domains: a public shortlink host and a private shortlink host. There are two environments, each with its own D1 database, KV namespace, Worker, and domains.

Environment	Public host	Private host	Worker	D1 database
dev	dev.heygo.cc	my.dev.junv.cc	heygo-dev	heygo-shortlinks-dev
prod	heygo.cc	my.heygo.cc	heygo	heygo-shortlinks

The Worker reads PUBLIC_HOST, PRIVATE_HOST, APP_BASE_URL, and COOKIE_DOMAIN from env vars (set in each wrangler config), so the same code serves every environment without hardcoded hostnames.

Prerequisites

• A Cloudflare account with the heygo.cc zone added (and junv.cc for dev's private host).
• A Cloudflare API token with D1, Workers KV, Workers Scripts, and Workers Routes permissions.
• Terraform >= 1.5 installed.

1. Provision infrastructure with Terraform

The terraform/ directory provisions the D1 database, KV namespace, and both Worker custom domains. See terraform/README.md for full details.

export CLOUDFLARE_API_TOKEN=***        # fill account_id + zone_ids first
npm run infra:init
npm run infra:plan:dev      # review, then:
npm run infra:apply:dev
npm run infra:plan:prod     # review, then:
npm run infra:apply:prod

2. Copy Terraform outputs into Wrangler configs

After infra:apply:dev, read the created resource IDs:

terraform -chdir=terraform output -var-file=environments/dev.tfvars

Paste the printed d1_database_id into wrangler.dev.jsonc (d1_databases[].database_id) and kv_namespace_id into wrangler.dev.jsonc (kv_namespaces[].id). Repeat for prod outputs into wrangler.prod.jsonc. The placeholder 00000000-... IDs are there until you fill them in.

3. Apply D1 migrations

npm run migrate:dev
npm run migrate:prod

4. Deploy the Worker

npm run deploy:dev
npm run deploy:prod

Dev environment cross-domain cookie caveat

In dev the private host my.dev.junv.cc lives on the junv.cc zone, while the app UI and auth flow are served from dev.heygo.cc (.heygo.cc cookie domain). A session cookie scoped to .heygo.cc is not sent to junv.cc, so private shortlink auth on my.dev.junv.cc will not work out of the box. Options:

• Use my.dev.heygo.cc (same .heygo.cc domain) as the dev private host instead — update terraform/environments/dev.tfvars and wrangler.dev.jsonc accordingly.
• Manually set the heygo_session cookie on junv.cc for local dev testing.

Prod does not have this limitation because heygo.cc and my.heygo.cc share the .heygo.cc cookie domain.

Current API skeleton

• GET /api/health returns JSON health status from the Worker.
• Unknown /api/* routes return JSON 404 responses.