mirror of
https://github.com/infrost/RaptorQR.git
synced 2026-08-30 06:28:23 +08:00
infrost
80 lines
3.2 KiB
Markdown
80 lines
3.2 KiB
Markdown
# RaptorQR Architecture
|
|
|
|
RaptorQR is a pnpm monorepo for camera-based QR transfer. The project is split so the protocol and codec code can become a reusable low-level library, while the CLI and web app remain consumers of that library.
|
|
|
|
## Monorepo Layout
|
|
|
|
```text
|
|
packages/raptorqr-core
|
|
src/protocol fixed header, CRC32C, transfer profiles
|
|
src/sender packetizers and frame scheduling
|
|
src/fec RaptorQ facade, deprecated JS RLNC, outer RS helpers
|
|
src/qr QR capacity, encode/decode facades, raster helpers
|
|
src/gif GIF parse/render helpers
|
|
src/reconstruct payload assembly
|
|
|
|
packages/raptorqr-wasm
|
|
src/fast_qr fast_qr wasm-bindgen artifacts and Colab script
|
|
src/raptorq cberner/raptorq wasm-bindgen artifacts and Colab script
|
|
|
|
packages/raptorqr-cli
|
|
src/raptorqr.ts CLI entrypoint
|
|
src/terminal_raster.ts terminal QR renderer
|
|
src/static_server.ts built web app preview server
|
|
|
|
apps/web
|
|
src/app Preact routes and UI
|
|
src/workers encode, decode, GIF, and QR render workers
|
|
src/lib app-local worker orchestration
|
|
src/tests browser/WebAssembly integration tests
|
|
```
|
|
|
|
## Package Boundaries
|
|
|
|
`@raptorqr/core` owns protocol behavior and public transfer APIs. It exports environment-neutral modules from `@raptorqr/core`, browser wrappers from `@raptorqr/core/browser`, and Node/CLI wrappers from `@raptorqr/core/node`.
|
|
|
|
`@raptorqr/wasm` owns generated WASM artifacts. Core imports fast_qr through `@raptorqr/wasm/fast-qr` and RaptorQ through `@raptorqr/wasm/raptorq`.
|
|
|
|
`@raptorqr/cli` depends on core and wasm. It bundles to `packages/raptorqr-cli/dist/raptorqr.js` and copies required WASM sidecars next to the bundle.
|
|
|
|
`@raptorqr/web` is private. It owns Vite, Preact UI, workers, and app-local worker pools. App-local `@/*` imports must not leak into packages.
|
|
|
|
## Protocol
|
|
|
|
The transport packet keeps the existing 8-byte header plus payload plus CRC32C trailer. The protocol does not add QR profile negotiation to the header; the receiver infers QR version from decoded symbols and packet payload size.
|
|
|
|
FEC codec detection uses the existing symbol index field:
|
|
|
|
* `symbolIndex = 0..23`: deprecated JS RLNC compatible packets
|
|
* `symbolIndex = 31`: primary RaptorQ WASM packets
|
|
|
|
`wasm-raptorq` is the default FEC codec. `js-rlnc` remains explicit and test-covered, but it is deprecated and is never used as an automatic fallback if RaptorQ WASM is unavailable.
|
|
|
|
## QR Encoding And Decoding
|
|
|
|
QR generation and FEC are separate layers:
|
|
|
|
* FEC codec: `wasm-raptorq` or deprecated `js-rlnc`
|
|
* QR encoder: `fast-qr-wasm` or `zxing-wasm`
|
|
|
|
fast_qr WASM exposes both RGBA rendering and raw matrix output. The web app uses RGBA output for live/GIF rendering; the CLI uses matrix output for terminal rendering.
|
|
|
|
ZXing WASM is used for decoding and remains available as a QR writer option in the browser.
|
|
|
|
## Build And Test
|
|
|
|
Root commands orchestrate package-level commands:
|
|
|
|
```bash
|
|
pnpm build
|
|
pnpm test
|
|
pnpm dev:web
|
|
```
|
|
|
|
The test split follows ownership:
|
|
|
|
* core: protocol, packetization, FEC, reconstruction
|
|
* wasm: generated RaptorQ artifact verification
|
|
* cli: terminal raster and CLI encode pipeline
|
|
* web: browser QR/GIF/ZXing/worker integration
|