Sidecar extension platform for modules that need a backend (Akahu bank feeds, NZ)

[JakeTheRabbit]

Built a sidecar extension platform for Yuvomi and it's public now: https://github.com/JakeTheRabbit/yuvomi-extensions

Short version: some modules need a server. Mine needed encrypted token storage, a scheduler, and a bank API. The rule I set myself was that Yuvomi stays on its official image and owns its own database - no core patch, no second writer on yuvomi.db. Everything goes through /api/v1 and the modules/ directory you already support.

What's in it:

• packages/server-runtime - encrypted SQLite (SQLCipher via better-sqlite3-multiple-ciphers), Yuvomi session auth, CSRF, readiness
• packages/yuvomi-client - bounded REST client plus OpenAPI capability evaluation
• packages/browser-sdk - same-origin browser client, plain ES modules, no build step
• plugins/akahu-agent - NZ bank feeds, household budgeting, AI-assisted transaction coding with deterministic rules on top
• contracts/ - the operations a plugin declares it needs

The part worth your attention regardless of the Akahu plugin is compatibility. A module today carries its own version in module.json and nothing about the Yuvomi it was written for, so when an endpoint moves the module keeps loading and fails at the point of use - mid-write, in front of the user. What I do instead is read /api/v1/version and the authenticated OpenAPI document, compare against a declared operation list, and drop to read-only rather than issue a write against an endpoint whose meaning changed. Stored data, review and export stay readable for diagnosis.

Two things I'd like:

1. A place for third-party modules to be found. MODULES.md tells people how to build one, but there's no index of what exists. Happy for this and yuvomi-grocery-optimiser to be the first two entries if you want one.

2. docs(modules): say how a module with its own backend stays safe #728 and docs(modules): say how a module survives a yuvomi upgrade #729 are two docs-only PRs against MODULES.md written from what I hit building this - one on what a module with its own backend service owes core, one on the compatibility check above. Both describe behaviour that already exists, no core change. Close them if you'd rather the module guide stayed lean, no hard feelings.

Also - thanks for taking #697. The token-subject work is what makes unattended posting in personal-budget mode possible at all; the extension design had it flagged as blocked until that landed.

MIT, same as core.

[ulsklyc]

This is the best possible outcome for the module system, and the rule you set yourself is exactly the right one - Yuvomi on its official image, owning its own database, everything through /api/v1 and modules/. A second writer on yuvomi.db would break in ways nobody could debug from either side, and you avoided it without being asked.

It also answers a question that keeps coming up in other threads. Health data import (#743, #639) runs into the same wall: OAuth against a third-party provider needs token storage, a scheduler and a server, and every provider integration taken into core is a permanent maintenance commitment for a single-maintainer project. A sidecar runtime means those can exist without each one becoming this repo's problem. Your Akahu feed is the concrete case; the pattern generalises.

One thing worth knowing if you have not hit it yet: the API has no change feed. Endpoints are read and write, but there is no "what changed since I last looked", so a sidecar that wants to stay in sync has to poll and diff. That is a genuine gap in /api/v1 rather than something you should work around forever - if it becomes the awkward part of your runtime, say so, because that is the kind of feedback the public API surface commitment exists for.

Thank you for building it in the open, and for the restraint in the design. Anyone landing here from a "can modules have a backend?" question should read this thread.

[ulsklyc]

@JakeTheRabbit Two things from your post that my reply skipped. #728 and #729 were both merged on 12 August - the sections in MODULES.md on a module with its own backend and on surviving an upgrade are yours. On an index of third-party modules: not in this repository for now. A list I do not test would read as an endorsement, and #1671 (installing a module from GitHub or a ZIP in Settings) is in review - what a listing means changes once an entry is one step away from an install, so I would rather decide the index together with that than before it. Until then this thread and docs/SCOPE.md point to your work.

[ulsklyc]

@JakeTheRabbit The decision I tied to #1671 is made now. Installing from GitHub or a ZIP is out since v2.77.0: an admin can do it under Settings -> Modules where the operator has enabled it (MODULES_ALLOW_WEB_INSTALL), and a new module arrives switched off until an admin approves it.

The answer to the index question is still no list in this repository or in the app. A module runs with the session of every member, there is no permission model it could declare and the server enforce, and what gets installed is a branch or tag that can change after the next push. A list I keep would read as a recommendation for code I cannot hold to what I reviewed - and since #1671 an entry would be one paste away from running.

What there is instead (#2065): authors set the GitHub topic yuvomi-module, and MODULES.md points to https://github.com/topics/yuvomi-module with a clear note that nothing found there is tested or endorsed. A community-run list (an awesome-yuvomi, say) is welcome and can be linked from there. The decision and what would reopen it - an enforced permission model in the manifest, approval bound to a commit SHA, and a second reviewer - are written down as entry 15 in docs/DECISIONS.md. To make the admin's own review easier, #2064 will show the installed commit and link the changes on replace.

So please add the topic to your repositories; that is the place people will find them. This thread stays open, since SCOPE.md points here for modules with their own backend.