NAHPU API

The NAHPU app uses Rust through Flutter Rust Bridge. The app’s rust/ crate is the rust_lib_nahpu wrapper crate: it exposes bridge-facing functions and types, while reusable implementations live in the NAHPU API workspace.

Use Data import and export to see which workflows cross this boundary and which remain Dart-owned.

What the API layer means

In the app repository:

rust/src/api/*.rs defines bridge-facing wrapper modules.
lib/src/rust/ contains generated Dart bindings.
rust/Cargo.toml declares the API crates linked into the app.
flutter_rust_bridge_codegen generate regenerates bridge code after wrapper API changes.
cargo check and cargo clippy verify the Rust wrapper and its integration.

The reusable Rust logic comes from these NAHPU API crates:

Crate	Used for
`nahpu_archive`	ZIP, tar.gz, and gzip archive creation and extraction
`nahpu_configs`	`redb` storage and export/import for user configs, record export presets, template presets, and document layouts
`nahpu_db`	Drift-derived Rust record models plus CSV, TSV, Excel, and JSON import/export helpers
`nahpu_dp`	Reproducible NAHPU Data Package planning, validation, and writing
`nahpu_dwc`	Darwin Core mappings, Darwin Core Archive, and Darwin Core Data Package bundles
`nahpu_export`	Markdown/Typst document rendering and PDF compilation
`nahpu_gis`	Coordinate conversion, GIS import/export, and vector-layer normalization

Data ownership

The API does not own every kind of persisted app data. Project records remain in the Flutter app’s Drift-managed SQLite database, while configuration, installation-local state, and files follow separate ownership boundaries. See the canonical Persistence data page for the complete storage model and the NAHPU-to-Darwin Core mapping.

Wrapper modules

The app exposes Rust behavior through rust/src/api/:

Module	Purpose
`archive.rs`	ZIP and tar.gz writer/extractor wrappers
`common.rs`	Bridge initialization and shared sanity helpers
`config.rs`	`nahpu_configs` models and configuration/preset operations
`document.rs`	Markdown-to-Typst conversion and Typst-to-PDF compilation
`dwc.rs`	Darwin Core header mapping and bundle plan/validate/write operations
`export.rs`	General record and tabular export wrappers
`gis.rs`	Coordinate conversion, coordinate exchange, and vector-layer wrappers
`import.rs`	Delimited and Excel record-reading wrappers
`nahpu_dp.rs`	NAHPU Data Package plan/validate/write operations

Generated files under lib/src/rust/ and rust/src/frb_generated.rs must not be hand-edited. Change the wrapper API and regenerate the bindings instead.

When to edit the app wrapper

Edit rust/src/api/ when you need to:

expose an existing API-crate function to Dart;
convert Dart-friendly inputs into crate-friendly Rust inputs;
map Rust errors into bridge-friendly result types;
add simple structs or enums that Flutter Rust Bridge can serialize.

Do not put durable domain logic in the wrapper. If behavior should be reused outside the Flutter app, or is a core parser, exporter, validator, converter, or package writer, implement it in the appropriate NAHPU API crate first.

Boundary rules

Keep wrapper functions and conversions small.
Prefer Result<T, String> or another bridge-friendly result over panics.
Avoid .unwrap() unless the invariant is local and documented.
Prefer primitive values, strings, byte lists, and simple structs at the Dart boundary.
Keep generated code out of manual edits.
Regenerate bindings after changing any bridge-facing Rust signature.

Adding a bridge API

Implement or update reusable behavior in the relevant nahpu_api crate.
Add a wrapper function or type in the appropriate rust/src/api/*.rs file.
Export a new wrapper module from rust/src/api/mod.rs when necessary.
Regenerate Flutter Rust Bridge bindings.
Terminal window
```
flutter_rust_bridge_codegen generate
```
Use the generated binding from the relevant Dart service.
Add focused tests for the Rust behavior, Dart service, or integration path.

Verify the change.

flutter analyze
flutter test
cargo check
cargo clippy