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 Objectboundary: 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.
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