Crate Structure
Version source of truth: root Cargo.toml [workspace.package] version.
Workspace members (crates/)
xberg — core library: extraction engine, MIME detection, plugin system, OCR, chunking, embeddings, API/MCP serverxberg-cli — CLI binary. Defines no cli feature of its own; its core-cli feature is what forwards to the core xberg/clixberg-ffi — C FFI layer; opaque handles, cbindgen headers. Consumed by Go (cgo), C# (P/Invoke), Zig (C ABI), Swift (swift-bridge shim, which injects the dependency itself) and Java (Panama FFM)xberg-jni — JNI bindings backing packages/kotlin-android. The Java package does not go through this: alef.toml [crates.java] sets ffi_style = "panama", i.e. Panama FFM over xberg-ffixberg-node — NAPI-RS Node.js/TypeScript bindingsxberg-py — PyO3 Python bindingsxberg-php — ext-php-rs PHP bindingsxberg-wasm — wasm-bindgen WASM bindings; wasm-target feature setxberg-native-pdf — pure-Rust PDF engine, vendored into this workspace. Path dependency with no package = alias, so the extern crate name is xberg_native_pdf. Exports LOG_TARGET_ROOT = module_path!(); derive log-target filters from that constant, never a string literalxberg-pdfium-render — pdfium FFI backend behind the pdf-pdfium feature. Aliased: pdfium-render = { package = "xberg-pdfium-render", … }, so call sites still write pdfium_render::xberg-paddle-ocr — PaddleOCR; ORT and tract engines. On WASM only paddle-ocr-types is available, but paddle-ocr is in windows-targetxberg-tesseract — Tesseract OCR bindingsxberg-candle-ocr — candle VLM OCR backends (TrOCR, PaddleOCR-VL, GLM-OCR, DeepSeek-OCR)xberg-gliner — GLiNER NER inferencexberg-libheif — libheif bindings for HEIC/HEIFxberg-libwpd — libwpd bindings for WordPerfect (.wpd)
Two members live outside crates/: packages/dart/rust and packages/swift/rust.
excluded — not members, and invisible to cargo check --workspace:
e2e/rust, packages/elixir/native/xberg_nif, packages/ruby/ext/xberg_rb.
default-members = ["crates/xberg", "crates/xberg-cli"].
Distribution packages (packages/)
python (PyPI/maturin), ruby (RubyGems/Magnus), php (Composer), go (cgo over xberg-ffi),
java (Maven, Panama FFM over xberg-ffi), csharp (NuGet, P/Invoke), elixir (Hex/Rustler),
dart (pub.dev, flutter_rust_bridge), kotlin-android (AAR; JNI over xberg-jni),
swift (SwiftPM, swift-bridge), zig (C ABI over xberg-ffi).
Tools (tools/)
benchmark-harness (the only workspace member here), generate_test_fixtures, ocr-measure,
perf.
There is no tools/e2e-generator — e2e generation is alef e2e generate, configured in
alef.toml [crates.e2e]. See the alef-generated-bindings skill.
Adding a workspace member
Adding to [workspace] members and to the Dockerfiles is not enough. Two ignore files use
"ignore everything, then allowlist", so a new crate is invisible to Docker and its vendor/
is never committed:
.dockerignore — * at the top, then a per-crate allowlist; add !crates/<name>/.
Missing it fails every image build with
failed to compute cache key: "/crates/<name>": not found..gitignore — bare vendor/ with per-crate un-ignores; add !crates/<name>/src/vendor/
if the crate vendors source. Missing it means git add -A commits nothing under vendor/
and a fresh clone will not build.- Every
docker/Dockerfile.* must either COPY crates/<name>/ or sed-exclude the member
from the workspace list.
- Run
task verify:docker-crates. It checks (1) and (3) in both directions — it also catches
a COPY line naming a crate that no longer exists. It does not look at .gitignore;
verify that by hand.
Deleting a crate is the same problem in reverse: a stale allowlist entry is what hides a
real omission.
1---2name: crate-structure3description: The Xberg workspace layout — the version source of truth (root Cargo.toml [workspace.package] version), the 19 workspace members and 3 excluded crates, the distribution packages under packages/, the tools/ directory, and the ignore-file allowlists a new workspace member must be added to. Load when navigating the repo, deciding where code belongs, or wiring a new crate or binding package.4---5
6# Crate Structure
7
8Version source of truth: root `Cargo.toml` `[workspace.package] version`.
9
10## Workspace members (`crates/`)
11
12- `xberg` — core library: extraction engine, MIME detection, plugin system, OCR, chunking, embeddings, API/MCP server
13- `xberg-cli` — CLI binary. Defines no `cli` feature of its own; its `core-cli` feature is what forwards to the core `xberg/cli`
14- `xberg-ffi` — C FFI layer; opaque handles, cbindgen headers. Consumed by Go (cgo), C# (P/Invoke), Zig (C ABI), Swift (swift-bridge shim, which injects the dependency itself) and Java (Panama FFM)
15- `xberg-jni` — JNI bindings backing `packages/kotlin-android`. The Java package does **not** go through this: `alef.toml [crates.java]` sets `ffi_style = "panama"`, i.e. Panama FFM over `xberg-ffi`
16- `xberg-node` — NAPI-RS Node.js/TypeScript bindings
17- `xberg-py` — PyO3 Python bindings
18- `xberg-php` — ext-php-rs PHP bindings
19- `xberg-wasm` — wasm-bindgen WASM bindings; `wasm-target` feature set
20- `xberg-native-pdf` — pure-Rust PDF engine, vendored into this workspace. Path dependency with **no** `package =` alias, so the extern crate name is `xberg_native_pdf`. Exports `LOG_TARGET_ROOT = module_path!()`; derive log-target filters from that constant, never a string literal
21- `xberg-pdfium-render` — pdfium FFI backend behind the `pdf-pdfium` feature. Aliased: `pdfium-render = { package = "xberg-pdfium-render", … }`, so call sites still write `pdfium_render::`
22- `xberg-paddle-ocr` — PaddleOCR; ORT and tract engines. On WASM only `paddle-ocr-types` is available, but `paddle-ocr` **is** in `windows-target`
23- `xberg-tesseract` — Tesseract OCR bindings
24- `xberg-candle-ocr` — candle VLM OCR backends (TrOCR, PaddleOCR-VL, GLM-OCR, DeepSeek-OCR)
25- `xberg-gliner` — GLiNER NER inference
26- `xberg-libheif` — libheif bindings for HEIC/HEIF
27- `xberg-libwpd` — libwpd bindings for WordPerfect (`.wpd`)
28
29Two members live outside `crates/`: `packages/dart/rust` and `packages/swift/rust`.
30
31`exclude`d — **not** members, and invisible to `cargo check --workspace`:
32`e2e/rust`, `packages/elixir/native/xberg_nif`, `packages/ruby/ext/xberg_rb`.
33
34`default-members = ["crates/xberg", "crates/xberg-cli"]`.
35
36## Distribution packages (`packages/`)
37
38`python` (PyPI/maturin), `ruby` (RubyGems/Magnus), `php` (Composer), `go` (cgo over xberg-ffi),
39`java` (Maven, Panama FFM over xberg-ffi), `csharp` (NuGet, P/Invoke), `elixir` (Hex/Rustler),
40`dart` (pub.dev, flutter_rust_bridge), `kotlin-android` (AAR; JNI over xberg-jni),
41`swift` (SwiftPM, swift-bridge), `zig` (C ABI over xberg-ffi).
42
43## Tools (`tools/`)
44
45`benchmark-harness` (the only workspace member here), `generate_test_fixtures`, `ocr-measure`,
46`perf`.
47
48There is no `tools/e2e-generator` — e2e generation is `alef e2e generate`, configured in
49`alef.toml` `[crates.e2e]`. See the `alef-generated-bindings` skill.
50
51## Adding a workspace member
52
53Adding to `[workspace] members` and to the Dockerfiles is not enough. Two ignore files use
54"ignore everything, then allowlist", so a new crate is invisible to Docker and its `vendor/`
55is never committed:
56
571. `.dockerignore` — `*` at the top, then a per-crate allowlist; add `!crates/<name>/`.
58 Missing it fails every image build with
59 `failed to compute cache key: "/crates/<name>": not found`.
602. `.gitignore` — bare `vendor/` with per-crate un-ignores; add `!crates/<name>/src/vendor/`
61 if the crate vendors source. Missing it means `git add -A` commits nothing under `vendor/`
62 and a fresh clone will not build.
633. Every `docker/Dockerfile.*` must either `COPY crates/<name>/` or `sed`-exclude the member
64 from the workspace list.
654. Run `task verify:docker-crates`. It checks (1) and (3) in both directions — it also catches
66 a `COPY` line naming a crate that no longer exists. It does **not** look at `.gitignore`;
67 verify that by hand.
68
69Deleting a crate is the same problem in reverse: a stale allowlist entry is what hides a
70real omission.
xberg-io