Skip to content

doc[notask]: simplify SDK family architecture diagrams - #3982

Open
yuranich wants to merge 5 commits into
mainfrom
docs-architecture-system-context
Open

doc[notask]: simplify SDK family architecture diagrams#3982
yuranich wants to merge 5 commits into
mainfrom
docs-architecture-system-context

Conversation

@yuranich

@yuranich yuranich commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

🎯 What problem does this PR solve?

  • The published SDK architecture diagrams were too dense: the same package mesh, transport matrix, and model-source story was repeated on every C4 page.
  • Labels did not match the planned split: @qvac/sdk is the host and worker shell, @qvac/inference is the engine the worker runs, registry bytes are not HTTP, and several domain fields were stale.

📝 How does it solve it?

  • Collapse system context to one SDK family plus registry, HTTP/CDN, and Holepunch.
  • Show the target runtime path Host Client → Bare Worker (RPC shell) → @qvac/inference, with direct Bare skipping the worker.
  • Keep two deployment topologies. Left is host plus worker (subprocess on Node/Python/Electron, same process on Pear and Expo). Right is direct Bare. Platform transports stay in a table.
  • Correct registry vs HTTP, model-source kinds, dispatch lookup, and domain names (blobCoreKey, workspace, events/final) without adding boxes.
  • Label wire edges as intent [transport]. Registry catalog and blobs use Holepunch (Hyperswarm plus a Hypercore blob store). HTTPS and Hyperswarm stay on their own edges.

🧪 How was it tested?

  • Rendered PlantUML sources to PNG with the architecture render script and reviewed the images.

Collapse duplicated C4 views, drop deprecated @qvac/bare-sdk from the runtime story, and hide misleading container stereotypes.
Name the worker as the RPC shell and the engine as @qvac/inference, and correct registry, domain, and dispatch labels.
@yuranich
yuranich requested review from a team as code owners August 21, 2026 09:40
@github-actions

Copy link
Copy Markdown
Contributor

Review Status

Current Status: ❌ PENDING
Approvals so far: none

Pending reviews: Needs 1 Management or Team Lead, and 1 more from Management, Team Lead, or Member.

@github-actions

Copy link
Copy Markdown
Contributor

License compliance — clean

No new dependency license findings in this PR.

Warn-only (shadow) mode — this check does not block merges yet.

Updated automatically by the canonical license compliance workflow.

NOTICE presence (advisory)

Missing NOTICE (advisory, does not block):

  • ./.github/actions/release-merge-guard
  • ./docs/website
  • ./packages/ggml-coload-smoke
  • ./packages/fabric/test/integration
  • ./packages/inference-addon-cpp/mobile
  • ./packages/sdk/e2e
  • ./packages/llm-llamacpp/benchmarks/performance
  • ./packages/llm-llamacpp/benchmarks/server
  • ./packages/vla-ggml/sim/server
  • ./packages/embed-llamacpp/benchmarks/performance
  • ./packages/embed-llamacpp/benchmarks/server
  • ./packages/asr-ggml/benchmarks/server

Put wire protocols in the C4 Rel technology slot and shorten component-diagram labels so arrows stay readable.
Treat Hyperblobs as a Hypercore blob store, not a protocol, keep the registry on the Holepunch box, and distinguish the SDK worker from direct Bare.
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.

1 participant