Skip to content

backend: Studio's generated OpenAPI and architecture documents ship in the Worker #494

Open

Description

@prisis

Problem

The backend Worker bundles two generated documents that only Studio reads:

  • backend/lunora/_generated/openapi.ts (about 892 KB of source, about 768 KiB in the bundle). Studio's API tab reads it.
  • backend/lunora/_generated/architecture.ts (about 572 KB of source, about 497 KiB in the bundle). Studio's Architecture view reads it, through GET /_lunora/admin/architecture.

Together they are about 1.26 MiB of the 13.8 MiB bundle, roughly 9%.

They do not add to startup. The generated app loads them in loadDeferredModules on the first event, so the measured startup (about 156 ms active with lazy functions) is not affected. They still count against the bundle size, the upload and the first request.

Our public API does not use them. /api/v1/openapi.json is built by backend/lunora/public-api/openapi.ts.

Why this needs a choice

We use Studio, and both views are useful, so removing the documents outright is not an option. The question is where they run and when they are loaded.

Options

  1. Status quo. Keep both in the Worker, loaded on the first event. Cost: about 1.26 MiB of bundle and the first-request evaluation. No work.
  2. Stop generating the OpenAPI spec for Studio (lunora codegen --api-spec openrpc, or none). Saves about 768 KiB. Cost: Studio's API tab loses its spec, unless it can read OpenRPC instead; this needs checking. --api-spec none also deletes the tracked openapi.{ts,json}, so they would have to be restored in CI. Keeps the architecture document.
  3. Load both documents only on Studio's route. Upstream change: the admin routes import the documents when they are requested, not in loadDeferredModules. Saves about 1.26 MiB on the common path, and Studio keeps working.
  4. Ship the documents as static assets. Codegen writes openapi.json and architecture.json; Studio fetches them through an authenticated asset route, or from R2 at deploy. The Worker no longer contains them. Needs an upstream change and a deploy step for us.
  5. Move the documents into their own Studio Worker. This fits the multi-Worker direction. Services can only be called from actions, so an HTTP admin route cannot call that Worker directly; it would need a proxy or a separate host. The largest change, worth it only if Studio grows.

Recommendation

Option 3 as the upstream request. Option 2 as a local stopgap if we want the saving now and do not need Studio's API tab.

Decision needed: do we keep Studio's API tab?

Acceptance

  • The Worker bundle shrinks by the amount the chosen option saves. Measure with pnpm --filter @neore/backend run build.
  • Studio's API and Architecture views still work in lunora dev and on a deploy.
  • The public /api/v1/openapi.json is unchanged.

Related

Activity

  1. prisis commented on Nov 5, 2026

    @prisis
    MemberAuthor

    Option 3 is up as anolilab/lunora#1499: Studio's architecture, OpenAPI and OpenRPC documents now load only when their admin route is requested, not on an isolate's first event.

    Caveat for neore: the backend builds with lunora build (wrangler/esbuild), which doesn't split code. After #1499 the documents are evaluated lazily, which takes them off the first request, but they stay in the uploaded file, so the bundle size here doesn't change. The acceptance item "the Worker bundle shrinks" still needs option 2 (--api-spec openrpc/none) or option 4 (ship the documents as static assets). The open decision on keeping Studio's API tab still applies.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions