1 ADR 0009 v1 modular extension boundaries
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

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 ProcessingIssue or 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.