These docs are a work in progress and may not be fully up to date. Some pages may contain internal notes for our team.
Skip to Content

Data model — Map

A Map is a named collection of Locations and Sets (Categories) that backs a Finder. Every Finder has exactly one Map, created automatically when the Finder is created.

Table: maps

ColumnTypeNullableDescription
idbigint (auto-increment)noPrimary key
titlevarcharnoMap name; mirrors the parent Finder’s title on auto-creation
descriptiontextyesOptional freetext description; set to "Internal backing map for finder scope." on auto-creation
created_attimestampnoLaravel auto-managed
updated_attimestampnoLaravel auto-managed

Relations

  • belongsToMany Finder — via finder_map pivot. In normal operation this is a 1:1 relationship — one Map per Finder. The pivot schema enforces finder_id and map_id with cascading deletes.
  • belongsToMany Set — via map_set pivot. Sets (called “Categories” in the UI) belonging to this Map.
  • belongsToMany Location — via map_location pivot (added in migration 2026_04_17). The locations that this Map surfaces to its Finder.
  • belongsToMany Workspace — via workspace_map/map_workspace pivot. Associates the Map with workspace(s).
  • belongsToMany User — via map_user pivot (owners). Returns only users.id for performance.

Paired Finder creation

A Map is always created as a side-effect of Finder creation, never independently. The logic lives in Finder::ensureBackingMap() (app/Models/Finder.php):

  1. A new Map is created with title copied from the Finder (or "Finder {id}" if the Finder has no title yet).
  2. The Map inherits the Finder’s owners (finder_user → map_user) and workspaces via syncWithoutDetaching.
  3. The Map is attached to the Finder via the finder_map pivot.
  4. The Map’s description is set to "Internal backing map for finder scope.".

Because ensureBackingMap is idempotent (wrapped in a DB transaction with an empty-check), it is safe to call repeatedly. It also handles the edge case where a Finder accumulated multiple Maps — it merges their sets and locations into the lowest-id Map and removes the extras.

See also: Finder data model for the full ensureBackingMap algorithm.

Computed / virtual attributes

None. The Map model has no $appends, no casts beyond defaults, and no overridden toArray.

Concepts