1 ADR 0001 long term domain boundaries
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0001: Long-Term Domain Boundaries for Ownership, Sharing, People, and Workers

Status: proposed Date: 2026-05-10

Context

Memories is intended to become a privacy-first, self-hosted/local-first family media system, not a clone of Immich and not a throwaway single-user photo index. The v1 baseline now explicitly prioritizes a future-aligned architecture over minimizing initial feature scope. The initial design should therefore capture the long-term ownership, sharing, metadata, people/face, and background-processing semantics early, even if delivery is sliced into smaller increments.

Several decisions are expensive to reverse later:

  • Whether originals are owned by Memories or referenced in-place.
  • Whether media ownership and shared-library visibility are the same thing.
  • Whether metadata is private, shared by default, or governed by group-specific policy.
  • Whether people/face records are owner-owned, group-owned, or destructively merged.
  • Whether background workers own domain state or only execute jobs for a core authority.
  • Whether backup/export can remain inspectable after family sharing and people collaboration are introduced.

The constitution requires original byte preservation, local-first ownership, explicit architecture decisions, future-aligned architecture, and self-hoster operability.

Terminology Dictionary

This ADR uses the following terms as canonical terminology. If future specs need different terms, they should explicitly update this dictionary or add a follow-up ADR.

  • Media Owner: The user who owns an original asset record and controls whether that asset, and which metadata about it, is contributed to a sharing group.
  • Stored Object: The immutable physical photo or video bytes stored inside the Memories-managed library and addressed by content identity. A stored object may be referenced by multiple owner-owned original asset records when bytes are exactly identical.
  • Original Asset: The owner-owned original media record created after upload commit. It references a stored object and carries owner-specific provenance, lifecycle, contribution, and metadata relationships.
  • Media Item: The application-level record for an original asset, including stable identity, extracted metadata, processing status, and links to derived assets or shared-library contributions.
  • Media Ownership: The relationship between a media owner and an original asset. Ownership remains with the owner even when the asset is visible in a shared library.
  • Shared-Library Visibility: Whether a media item is visible to members of a sharing group through an explicit contribution. Visibility can be granted or revoked without transferring ownership or deleting the owner original.
  • Sharing Group: A group of users with shared access rules and trust assumptions, such as a family. Each group can have different default metadata sharing policies.
  • Shared Library: The group-visible collection formed by contributions from one or more media owners. A shared library is not the owner of the originals.
  • Contribution: An explicit act or record that makes an owner-controlled media item, and the metadata allowed by policy, visible in a shared library.
  • Metadata Sharing Policy: A per-owner, per-sharing-group default that defines which metadata classes are included with contributions, such as location, ratings, edits, face regions, and person assignments.
  • Contribution Override: A per-contribution exception to the owner's default metadata sharing policy for a specific shared asset.
  • Provenance: Traceable origin information for data, including which owner, group member, worker, source asset, or workflow created or contributed it.
  • People/Face Metadata: Metadata about detected faces, face regions, face clusters, person records, and assignments between faces and people.
  • Person Record: A provenance-preserving record representing a person as identified by an owner or group workflow. Person records are not destructively erased by group merges.
  • Group Person: A group-level projection or managed aggregate that lets a sharing group treat multiple person records as the same person while retaining the underlying records and provenance.
  • Person Merge Request: A request to associate multiple person records with one group person, resolved according to affected owners' merge policies.
  • Person Merge Policy: A per-owner, per-sharing-group rule defining whether that owner's person records may be merged automatically, require owner approval, or may not be merged.
  • Background Worker: A process that performs long-running or compute-intensive jobs, such as preview generation or face detection, without owning authoritative domain state.
  • Authoritative Metadata: Non-regenerable metadata whose current value is owned by the core application state and must be backed up and restored, such as sharing policies, contribution state, person provenance, and album membership.
  • Derived Asset: A generated thumbnail, preview, transcode, or cache artifact derived from an original asset. Derived assets are regenerable unless a later decision marks a specific class as authoritative.

Options Considered

Option Summary Benefits Costs / Risks
A Minimal single-owner core first; add family sharing, people, and workers later Fastest first implementation; fewer immediate entities and workflows High migration risk; likely breaking changes to ownership, authorization, metadata provenance, backup/export, and person identity semantics
B Full collaborative platform immediately Captures long-term intent and exposes all workflows early High implementation complexity; high risk of unfinished surface area; more operational burden before core trust is proven
C Future-aligned domain model with incremental delivery Captures stable long-term boundaries early while allowing small testable slices More upfront modeling and ADR/spec work; some modeled capabilities may exist before polished UI workflows

Decision

Choose Option C: Future-aligned domain model with incremental delivery.

The initial architecture will model the intended long-term family-memory domain explicitly, while implementation may expose only validated slices at first. The following boundaries are accepted as architectural direction:

Media Ownership Boundary

  • Memories uses an app-managed canonical library for v1.
  • Upload commit copies or links original media bytes into a Memories-owned storage layout as immutable Stored Objects.
  • Managed stored objects are authoritative media bytes and MUST NOT be modified by application workflows.
  • A Media Owner owns Original Asset records even when the referenced stored bytes are physically deduplicated with another owner's identical upload.
  • Deleting or reversing a shared-library contribution MUST NOT delete the owner's original asset.
  • Permanent deletion of one owner's original asset MUST NOT remove stored bytes still referenced by another active, trashed-within-retention, or otherwise restorable original asset.

Sharing Boundary

  • Sharing is modeled through Sharing Groups and Shared Libraries.
  • A family is the primary high-trust sharing group, but the model must not assume all groups have family-level trust.
  • A Shared Library contains contributions from one or more media owners.
  • Contribution is explicit and reversible.
  • Media ownership and shared-library visibility are separate concepts.

Metadata Authority and Provenance Boundary

  • Each media owner can configure per-group Metadata Sharing Policies.
  • Metadata classes shared with a group may include location, ratings, edits, face regions, person assignments, and future metadata classes.
  • Family groups may have more permissive defaults than non-family groups.
  • Metadata contributed to a shared library must preserve provenance: source media, contributing owner, creator when different, and acceptance/approval state where relevant.
  • The authoritative metadata store will be decided in implementation planning or a follow-up ADR, but exported metadata must remain inspectable and sufficient for backup/restore/exit.

People and Face Boundary

  • Local face detection and clustering are part of the family-memory direction and may be included in v1 as the local people pipeline.
  • Face regions, person clusters, and person assignments retain provenance.
  • Worker-suggested face/person assignments are tentative owner-private metadata until the media owner confirms them. Tentative assignments are not visible to other users, are not accepted shared metadata, and cannot trigger contribution filters.
  • Owner-created face/person metadata remains intact when an asset is shared, subject to that owner's group sharing policy.
  • Group members may identify faces or assign people on contributed assets only when the media owner's per-group permissions allow it.
  • Owner approval may be required before group-created face/person annotations become accepted metadata for the contributed asset.
  • A Person Record remains provenance-preserving. Person merge must not destructively erase original owner/person records.
  • A Group Person should be treated as a group-level projection or managed aggregate over underlying owner/person records unless a future ADR explicitly chooses a different model.
  • ADR 0012 refines Group Person semantics for trusted family groups: group people are stable collaborative identities over contributed, group-eligible faces/person links, with separate owner-side and group-side authority, while owner-local person spaces remain durable personal truth.
  • Group members may request merging person records into a group-level person.
  • Affected owners control per-group merge policy: allow by default, require approval, or disallow.

Background Worker Boundary

  • Long-running or compute-intensive work must have a service boundary so it can run outside the core application process and, where useful, on another machine.
  • Examples include preview generation, video processing, face detection/clustering, OCR, and future media analysis.
  • Workers are executors, not owners of authoritative domain state.
  • The core application owns authorization, job orchestration state, authoritative metadata acceptance, and backup/export semantics.
  • Workers may produce derived assets, candidate metadata, and job results, but those results become authoritative only through the core application's accepted workflows and policies.
  • Worker access must respect media owner, sharing group, contribution, and authorization boundaries.

Backup, Restore, and Export Boundary

  • Backup must distinguish originals, authoritative metadata, processing/job state needed for recovery, and regenerable cache data.
  • Derived assets are cache unless explicitly marked otherwise.
  • Person/face provenance, sharing policies, contribution state, and merge state are non-regenerable metadata and must be included in backup/restore/export once implemented.
  • Export must allow a technically comfortable self-hoster to inspect core media, sharing, album, metadata, and people relationships outside the application.

Consequences

  • The data model will be more explicit from the beginning: media owners, sharing groups, contributions, metadata policies, people/face provenance, merge policy, and worker jobs are first-class concepts.
  • Physical storage deduplication adds an explicit Stored Object boundary: byte storage can be shared while ownership, lifecycle, sharing, and metadata stay separate.
  • v1 implementation can still be sliced, but shortcuts that assume a single owner, a single global library, no provenance, or workers owning domain truth are rejected.
  • Family sharing can become more natural than Immich-style cautious per-asset metadata isolation, while still allowing group-specific privacy controls.
  • Backup/export design must account for collaborative metadata and people/face state earlier.
  • The system avoids foreseeable breaking changes around person identity, shared-library contribution semantics, and distributed processing.
  • Planning must explicitly decide which modeled capabilities are user-facing immediately and which are only represented in stable model/API boundaries at first.
  • Operational complexity increases: authorization, job state, approval queues, and merge governance must be observable and recoverable.

Revisit Triggers

Revisit this decision if these assumptions change:

  • Memories narrows back to a single-user archive rather than family/group collaboration.
  • The people/face pipeline is removed from the product direction.
  • App-managed original storage proves unacceptable and index-in-place becomes the canonical ownership model.
  • Distributed workers are no longer required or become too costly to operate safely for a self-hoster.
  • A future requirement needs public sharing, cloud sync, or multi-household federation that changes the trust and authorization model.
  • Backup/restore/export cannot remain inspectable with the chosen people/sharing/provenance model.
  • The group person projection model proves unable to support expected family workflows without excessive complexity.