Skip to content

docs: storage limits, Cloudflare deploy, and storage error reference#5

Open
openrijal wants to merge 2 commits into
awecode:mainfrom
openrijal:docs-storage-limits-and-deploy
Open

docs: storage limits, Cloudflare deploy, and storage error reference#5
openrijal wants to merge 2 commits into
awecode:mainfrom
openrijal:docs-storage-limits-and-deploy

Conversation

@openrijal
Copy link
Copy Markdown

Closes #4.

Summary

Adds three operational docs that cover production gaps in JSON admin:

  • docs/storage-limits.md — GitHub Contents API 1 MB inline limit, Blobs API 100 MB ceiling, sizing table by row size, write amplification, and when to move off single-file `array` storage.
  • docs/deploying-cloudflare-pages.md — per-request token-injection middleware pattern for runtimes where `runtimeConfig` is frozen and secrets live on `event.context.cloudflare.env` instead of `process.env`. Includes a runnable middleware example, env-var checklist, and verification steps.
  • docs/error-reference.md — every `createError` thrown by `server/utils/githubContents.ts` and `server/utils/jsonStorage/*` with status code, exact message, cause, and remediation. Reflects the post-fix: fall back to git blobs API for github files >1MB #3 Blobs API fallback path.

Cross-links the new pages from `README.md` and `docs/json-admin.md`.

Audit notes

A prior external audit claimed `docs/json-admin.md`, `docs/autoadmin-roles.md`, and `docs/development.md` were truncated mid-sentence. I verified each against actual repo source — they are not truncated. The audit also flagged missing reference docs (full `nuxt.config.ts`, auth integration guide, S3 walkthrough, DB migration guide). Those are real but out of scope here; happy to take them on as follow-ups.

Test plan

  • Verified every message in the error reference exists in source (grepped each `createError` call against the listed file).
  • Verified middleware example compiles against current types in the repo.
  • Sizing-table numbers are approximate by design — comfortable/slow/ceiling bands tie back to the documented GitHub limits.
  • Render check in your docs site / GitHub markdown viewer.

openrijal and others added 2 commits May 20, 2026 09:54
Add three operational docs that cover production gaps in JSON admin:

- docs/storage-limits.md: GitHub Contents API 1 MB inline limit, Blobs
  API 100 MB ceiling, sizing table by row size, write amplification, and
  when to move off single-file array storage.
- docs/deploying-cloudflare-pages.md: per-request token-injection
  middleware pattern for runtimes where runtimeConfig is frozen and
  secrets live on event.context.cloudflare.env instead of process.env.
- docs/error-reference.md: every createError thrown by
  server/utils/githubContents.ts and server/utils/jsonStorage/* with
  status code, exact message, cause, and remediation. Reflects the
  post-fix Blobs API fallback path.

Cross-link the new pages from README.md and docs/json-admin.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: operational gaps for JSON admin (storage limits, serverless deploy, error reference)

1 participant