Services

2026 06 16 Final

Final Cloudflare implementation review — 2026-06-16

Scope: synthesis of the Cloudflare skill-guided inventory and focused implementation reviews under docs/cloudflare-review/.

No Cloudflare APIs were called, no deployments were run, no DNS was mutated, and no secrets were printed during this review.

Loaded guidance#

The review loaded and applied:

  • Cloudflare Skills Index: /home/vchavkov/.config/brain/notes/skills/cloudflare/INDEX.md
  • Cloudflare Pages skill
  • Cloudflare Workers skill
  • Cloudflare Storage skill
  • Cloudflare DNS skill
  • Service Registry skill

Key guidance applied: prefer Wrangler for Pages/Workers deploys, keep KV/D1/R2 bindings explicit, separate Cloudflare public-zone ownership from Service Registry-owned svc.*/split-horizon/Caddy ownership, and keep tokens/secrets out of repo artifacts.

Audited artifacts#

  • docs/cloudflare-review/2026-06-16-skill-inventory.md
  • docs/cloudflare-review/2026-06-16-opennext-pages-review.md
  • docs/cloudflare-review/2026-06-16-manager-cloudflare-review.md
  • docs/cloudflare-review/2026-06-16-deployment-docs-review.md

Primary implementation surfaces reviewed:

  • apps/academy OpenNext/Worker config and Cloudflare build script
  • apps/blog OpenNext/Worker config and www service-binding route shape
  • apps/manager Cloudflare Pages static SPA config
  • Repo Cloudflare task/docs surfaces in .mise.toml, package.json, .github/workflows/cd.yml, .docs/cloudflare-deployment.md, hosting inventory, performance docs, and smoke-check docs

Overall verdict#

The repo has a substantial Cloudflare deployment surface and a useful centralized mise command layer, but several production-readiness gaps remain before broad Cloudflare health/deploy claims should be considered reliable.

There are no identified P0 issues in the reviewed files. The main P1 risks are deployment correctness and runtime binding drift: academy still needs a KV binding decision, manager production deploys need explicit branch/API-origin handling, and route/health checks need to match the actual Cloudflare/registry ownership model.

Findings by priority#

P0#

None found.

P1 — fix before relying on production Cloudflare deploy/health claims#

  1. Academy OpenNext KV binding drift

    • Academy enables kvIncrementalCache in apps/academy/open-next.config.ts, but apps/academy/wrangler.jsonc has no NEXT_INC_CACHE_KV binding.
    • Recommended action: either provision and bind a production KV namespace, or remove the KV incremental-cache override and update docs accordingly.

  2. Manager Pages production deploy does not pin the production branch

    • Manager deploy commands omit an explicit branch while www pins --branch main.
    • Recommended action: confirm the assistance-manager production branch and add --branch main or the confirmed production branch to both repo deploy surfaces.

  3. Manager production API origins are not enforced

    • Build/runtime fallback behavior can point a Cloudflare-hosted Manager browser at dev-style ports on the current host when VITE_AUTH_URL, VITE_API_URL, or VITE_LEARN_API_URL are absent.
    • Recommended action: require explicit production public API origins in CI/Pages env and document/add VITE_LEARN_API_URL where appropriate.

  4. Route and smoke-check targets do not match repo-declared Cloudflare routes

    • cf:health and prod:smoke probe flat hostnames, while inspected route declarations include path-based routes for docs and no repo-declared routes for several Workers apps.
    • Recommended action: decide canonical URLs per app, then update Wrangler route desired state and health/smoke tasks to match.

P2 — important documentation/operator hygiene#

  1. Cloudflare DNS vs Service Registry ownership is blurred in .docs/cloudflare-deployment.md

    • Recommended action: rewrite DNS guidance around public Cloudflare zones versus registry/Linode/split-horizon zones.

  2. Custom-domain desired state is underdocumented

    • Manager and some Worker-hosted apps depend on hostname bindings/routes that are not fully represented in repo config.
    • Recommended action: document source of truth per hostname: Wrangler route, Pages custom domain, registry-managed record, or external dashboard state.

  3. Token naming and scope guidance is inconsistent

    • Skill baseline prefers CF_API_TOKEN with CLOUDFLARE_API_TOKEN as compatibility alias; repo preflight requires CLOUDFLARE_API_TOKEN.
    • Recommended action: document this repo’s required env vars/scopes or make preflight accept the alias safely.

  4. Verification matrix is incomplete

    • Build, deploy, route health, link checks, local performance smoke checks, and artifact budgets are not clearly separated for every Cloudflare-hosted app.
    • Recommended action: add a matrix to .docs/cloudflare-deployment.md and avoid claiming full Cloudflare health from narrow checks.

Changes applied during the review#

  • Added the Cloudflare implementation inventory.
  • Added focused review docs for OpenNext apps, Manager Pages, deployment/task/docs surfaces, and this final synthesis.
  • Applied two low-risk implementation/doc fixes from the OpenNext review:
    • apps/academy/package.json: ensure OPEN_NEXT=1 is present on the actual next build and OpenNext build commands for build:cf.
    • apps/blog/open-next.config.ts: fix the comment reference from non-existent DEVELOPER.md to .docs/developer.md.

Verification evidence#

Recorded by the workers and re-checked where needed:

1
mise exec -- prettier --check docs/cloudflare-review/2026-06-16-skill-inventory.md
2
Checking formatting...
3
All matched files use Prettier code style!
1
mise run cf:build:manager
2
✓ 2955 modules transformed.
3
✓ built in 8.73s
1
mise exec -- pnpm exec node tools/scripts/check-cloudflare-artifact-budgets.mjs --app manager
2
manager: 11 files from apps/manager/build
3
  OK   javascriptGzip: 319.0 KiB / 1.50 MiB
4
  OK   assetsRaw: 1.12 MiB / 15.0 MiB
5
  OK   largestAssetRaw: 383.5 KiB / 4.00 MiB
6
  OK   workerRaw: 0 B / 1.00 MiB
1
mise exec -- pnpm --filter academy exec node -e "const p=require('./package.json'); console.log(p.scripts['build:cf']); if(!p.scripts['build:cf'].includes('OPEN_NEXT=1 next build')) process.exit(1);"
2
pnpm run content:build:fast && OPEN_NEXT=1 next build && OPEN_NEXT=1 npx opennextjs-cloudflare build --skipNextBuild --dangerouslyUseUnsupportedNextVersion
1
mise exec -- pnpm exec prettier --check docs/cloudflare-review/2026-06-16-opennext-pages-review.md apps/academy/package.json apps/blog/open-next.config.ts
2
Checking formatting...
3
All matched files use Prettier code style!
1
mise exec -- pnpm exec prettier --check docs/cloudflare-review/2026-06-16-manager-cloudflare-review.md
2
Checking formatting...
3
All matched files use Prettier code style!
1
mise exec -- pnpm exec prettier --check docs/cloudflare-review/2026-06-16-deployment-docs-review.md
2
Checking formatting...
3
All matched files use Prettier code style!

This evidence is narrow: it proves the reviewed files and selected Manager/OpenNext checks above, not a full workspace build, full deployment, DNS propagation, Cloudflare route health, or end-to-end application health.