Beanconqueror and roaster interoperability for beans, recipes, and machine profiles

[MaxRink]

Several existing discussions already cover adjacent Decaid concepts:

• #61 Beans API covers beans, batches, and inventory.
• #516 Recipes as first-class citizens covers reusable combinations of beans, grinders, profiles, and drink instructions.
• #707 Smart grinder integration and assisted dial-in covers grinder control and recommendations.

This discussion is deliberately narrower: how should Decaid exchange bean, recipe, grinder, and machine-profile data with Beanconqueror and with roasters that publish preparation data?

Why this is useful

Decaid already has useful local building blocks. Its current workflow can reference a bean batch and grinder while carrying target dose/yield and the selected grinder setting (current WorkflowContext). It also has documented profile create and batch-import operations (profile API documentation).

Beanconqueror already stores much of the corresponding data:

• Bean fields, including weight, EAN, and rating
• Brew fields, including bean, grinder, grind setting, dose, notes, and rating
• Protobuf bean-share links
• ZIP backup interchange containing Beanconqueror.json

Roasters are starting to publish machine-readable bean data alongside preparation guidance. For example, Kaffeemacher's Apas page links directly to a Beanconqueror import and publishes water, machine, grinder, and grind-setting recommendations.

Proposed ownership model

Decaid and Beanconqueror should remain cooperative peers rather than silently overwriting one another:

• Decaid owns the live shot and active workflow used to operate the machine.
• Beanconqueror remains independently useful on a phone or tablet.
• Import/export is explicit and previewable.
• Imported records retain their source, external identifier, source URL, source version/hash, and the time they were imported.
• A repeated import updates only fields the user accepts; it does not silently replace local edits.

A small mapping record would likely be needed for provider, entityType, externalId, localId, and source version/hash. The exact persistence/API design should follow agreement on the interchange contract rather than precede it.

Staged integration

1. Explicit import/export

• Import Beanconqueror bean-share links or QR codes into an editable Decaid preview.
• Support deterministic manual export/import using documented fixtures.
• Preserve unknown provider fields so a round trip does not unnecessarily destroy data.
• Report unsupported or ambiguous fields instead of guessing.

2. Stable interchange contract

Work with Beanconqueror on a documented, versioned subset covering beans/batches, grinders, brews/shots, tasting notes, and links to recipes or profiles. This should include fixture examples and clear unit/enum mappings.

3. Conflict-safe synchronization

Only design automatic two-way sync after there is a supported Beanconqueror app, LAN, file, or server boundary. Beanconqueror's current optional-server discussion is still a future design and calls out multi-device conflict handling; it should not be treated as an existing sync API.

Decaid also needs durable content-revision semantics for edited shots before incremental sync is reliable; that is already tracked in issue #676.

Roaster-published recommendations

A roaster offer could contain:

• bean identity and descriptive data;
• batch-independent preparation guidance;
• dose, target yield, temperature, water, grinder model, and grinder setting;
• a Decaid-compatible machine profile or a link to one;
• provenance URL, publication version/hash, and optional validity notes.

The import UI should distinguish facts about the bean from recommendations tied to a particular grinder or machine. A published machine profile must go through Decaid's normal profile parsing/import path, remain visibly attributed to its source, and must not become the active profile or be sent to the machine without an explicit user action.

Stable identity matters here, so this also overlaps #40 Stable IDs for profiles.

Questions

1. Which Beanconqueror format is the best supported starting point: bean-share links, backup JSON, or a new deliberately small interchange format?
2. Should external identity live in core records, a separate mapping table, or namespaced metadata initially?
3. Which roaster fields should be portable recommendations, and which should remain human-readable notes?
4. How should a roaster publish a Decaid machine profile and its compatibility constraints?
5. Would Beanconqueror and Decaid maintainers be interested in maintaining shared versioned fixtures before considering synchronization?

Related discussions

• #61 Beans API
• #62 Grinders API
• #64 Wiring beans/grinders/equipment into Workflow
• #66 Shot record metadata fields
• #516 Recipes as first-class citizens
• #707 Smart grinder integration and assisted dial-in