ADR 0009: v1 Modular Extension Boundaries
Status: proposed Date: 2026-05-10
Context
Memories has several places where replacement or extension is valuable: ML models, worker capabilities, media processors, storage backends, importers, search/indexing, backup/export transports, auth providers, maps/geocoding, and notifications. At the same time, Memories' core value depends on stable ownership, privacy, sharing, deletion, metadata authority, backup/restore, and provenance semantics.
A generic plugin system would be attractive in name but expensive in practice. It would require trust boundaries, sandboxing, API compatibility guarantees, secret handling, filesystem policy, upgrade strategy, support expectations, and debugging tools before the core product is validated.
The v1 design should therefore create durable modular seams without opening arbitrary extension hooks.
Decision
v1 does not implement a generic third-party plugin system.
Instead, v1 uses explicit modular boundaries where subsystem output is derived, replaceable, adapter-like, or operationally distinct. Modules interact with the Core API through typed contracts, capability declarations, profiles, and versioned records rather than arbitrary code hooks.
The Core API remains the non-pluggable authority for:
- media ownership;
- user/group authorization;
- sharing policy;
- deletion/trash/permanent-delete semantics;
- authoritative metadata acceptance;
- contribution snapshots;
- backup/restore/export truth;
- worker leasing and result acceptance;
- audit/processing issue visibility.
Accepted Modular Boundaries
| Boundary | v1 stance | Future extension path |
|---|---|---|
| Worker capabilities | Workers advertise capabilities and claim compatible jobs | Add new job types/protocol versions without direct DB access |
| ML models | Core API-managed MLModelProfiles select models for face and visual-concept tasks |
Add models/runtimes/hardware profiles while preserving result provenance |
| Media processing profiles | Derived assets use generation versions and worker artifacts | Add thumbnail/transcode profiles and regenerate stale assets |
| Storage backend | filesystem implemented behind backend-neutral keys |
Add S3/object storage as a backend, not a domain identity change |
| Importers | v1 browser/API/CLI only, with source provenance | Add Immich/Takeout/Apple/Synology/PhotoPrism import adapters as upload-session clients |
| Search/indexing | v1 basic search/filtering only | Add full-text/vector/semantic/object/person indexes behind search service boundaries |
| Backup/export transport | v1 local documented dump/export | Add remote targets/schedules without redefining fidelity restore truth |
| Auth providers | v1 local accounts | Add OIDC/LDAP later while preserving media-owner identity boundaries |
| Map tile providers/geocoding | v1 supports configurable tile providers for Map rendering per ADR 0018; reverse geocoding remains deferred | Add provider-specific place/geocoding adapters later without making location metadata provider-owned |
| Notifications/events | Deferred | Add webhooks/ntfy/email/Home Assistant sinks from structured domain/audit events |
Rules For Adding A Module Boundary
A future module boundary is acceptable when:
- the Core API can validate and accept/reject its output;
- authoritative state remains inspectable and backed up in Core API/PostgreSQL/export records;
- results include provenance, version, and configuration identity where relevant;
- failure can be surfaced as
ProcessingIssueor equivalent operator-visible state; - removing or replacing the module does not break ownership, sharing, deletion, or backup semantics.
A future module boundary is not acceptable when it would let external code bypass owner authorization, mutate originals, write authoritative database rows directly, delete media, change sharing policy, or silently rewrite accepted metadata without provenance.
Consequences
- Memories gets practical plug-and-play behavior for ML models, workers, media processing, storage, and future importers without committing to a broad plugin platform.
- Extension seams are testable because they are contracts and profiles, not arbitrary runtime hooks.
- Some implementation tasks should define internal interfaces even when only one v1 implementation exists.
- v1 avoids the operational and security burden of plugin sandboxing.
- Future contributors may need ADRs/specs when adding new module classes rather than dropping in arbitrary plugins.
Deferred
Generic third-party plugins, plugin marketplace/discovery, sandboxed untrusted code execution, script hooks, arbitrary filesystem hooks, user-installed UI extensions, and pluggable authorization/deletion/sharing policies are deferred and should require a separate ADR before implementation.
Revisit Triggers
Revisit this decision when Memories has stable core APIs, multiple real importer/search/storage/notification integrations, demand for third-party extensions, or a credible sandboxing and compatibility story.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference