shopdb-flask/docs/adr/ADR-017-buildings-and-levels.md

ADR-017: Buildings and levels as the map model

• Status: ACCEPTED
• Date: 2026-08-17
• Deciders: ShopDB maintainers
• Relates to: ADR-001 (asset as the platform contract), ADR-004 (per-site instances), ADR-010 (frontend plugin hooks), ADR-015 (site-specific configuration)
• Supersedes: the site-wide map_blueprint_light / map_blueprint_dark / map_width / map_height settings

Context

A site's floor map is one image. Four settings describe it - two blueprints (light and dark) and the native pixel width and height - and assets.mapx / assets.mapy are absolute pixel coordinates in that image's space.

That model has one floor in one building, which was true when it was written and is no longer. The reference site is adding a second level, and a second building is likely within a year or two. The immediate trigger is a new blueprint at 3308x4000 where the old one was 3300x2550.

The obvious cheap answer is to stack levels on one canvas: draw the second level below the first and keep one image. It works, and it was seriously considered. It was rejected because it makes the level an inference rather than a fact:

• "Which level is this asset on" becomes mapy > 2550. Every per-level filter, count, report and export has to know that constant, and re-exporting the drawing at a different height silently changes the answer everywhere. Not broken - wrong, which is worse.
• Distance between two markers becomes computable and meaningless, so anything doing nearest-asset or clustering quietly answers nonsense across levels.
• One canvas forces one scale. A mezzanine drawn at a different scale than the floor below cannot be expressed at all.
• 3308x4000 is portrait for a building whose floor is landscape. At a zoom where a marker is clickable, roughly half a level is visible, and "fit to level" is not expressible.
• A third level makes each of these worse, and adds a second threshold.

Timing decided it. Because the level layout changed and machines moved, every marker is going to be repositioned anyway. Introducing levels now costs one pass over the positions; stacking now and splitting later costs two, and in between every position placed encodes the threshold into real data - which a later migration would then have to un-guess by comparing Y against it.

Decision

Two tables, and assets reference the level.

buildings   buildingid, buildingname, sortorder, isactive
maplevels   levelid, buildingid, levelname, sortorder,
            blueprintlight, blueprintdark, mapwidth, mapheight,
            isdefault, isactive
assets      levelid  (nullable; the default level for existing rows)

1. An asset references the level, never the building. The building derives from the level, so the two cannot disagree. Storing both would be a fact recorded twice with no difference in granularity to justify it.

2. Blueprints and native dimensions belong to the level. This is what the site-wide settings could not express: two levels in one building may be drawn at different sizes and scales, and two buildings certainly are.

3. Name and order are separate. levelname is text and sortorder is an integer. Levels are not reliably numbered - basement, ground, mezzanine, roof, tunnel - and sort order gives adjacency and up/down navigation without pretending the names are ordinal. It also lets a mezzanine be inserted between two existing levels without renumbering anything.

4. mapx / mapy keep their meaning, scoped to the level. They stay absolute pixels in the native coordinate space of the level's blueprint. No normalisation to fractions: pixels are what the drawing tools produce, what an operator can read off an image, and what the existing data already holds.

5. A level is required to render a position, and absence is not a default. Where a payload carries a position without a level, the UI renders "level unknown" rather than falling back to the default level. Falling back draws one building's ground floor with a marker positioned for another building's mezzanine: it renders perfectly and points at the wrong place, and nothing about the result looks wrong. A visible gap is worth more than a confident wrong answer.

6. The level list is readable without authentication. The printer installer map runs optional-auth, before anyone logs in, and it needs a blueprint. This follows the precedent already set for printer install-list and the slide feed. Blueprint paths and level names are not secrets; the positions of assets on them already render on public kiosk pages.

7. Levels are not Locations. Assets carry locationid already, and reusing it is tempting. A Location answers "which operation owns this"; a level answers "which drawing renders it, at what native size". Overloading Location with blueprint images and pixel dimensions makes both concepts worse. They coexist: an asset on level 2 in operation 0613.

Migration

The existing four settings become one building and one level, marked default, and every asset with a position points at it. Nothing renders differently on the day it lands. The settings keys are then retired rather than left as a second source of truth that can disagree with the rows.

Consequences

Positive:

• A second building costs a row and a blueprint. So does a third level.
• Per-level export, per-level zoom, and per-level calibration all become expressible. Calibrating one level against its own landmarks is more correct than transforming a whole site at once.
• Level becomes queryable - counts and filters per level or per building are ordinary queries rather than coordinate arithmetic.

Negative:

• Every surface that draws a marker learns there is more than one drawing. That is two components, seven views, four asset position pickers, the printer installer map, the PDF export, and eight API payloads that must emit levelid beside mapx. A payload that forgets it produces the silent-wrong-map failure described above, which is why rule 5 exists and why a build gate checks that the two fields travel together.
• get_map_overlays gains level context, so this is a plugin contract change (0.20.0) and plugins rendering overlays need to declare which level they are for.
• One more admin surface: levels and buildings have to be managed somewhere, and the existing floor-map settings page becomes that.

Alternatives considered

Stack levels on one canvas. Rejected above. Zero cost today, and it makes the level an inference over a magic number.

Normalise coordinates to fractions of the image. Would make a rescaled blueprint self-correcting, which is genuinely attractive. Rejected for now because it converts every existing integer position through a lossy division, and because it does not help the actual problem: the levels changed and machines moved, so the positions need human review regardless. Worth revisiting independently.

A level string on the asset, with one blueprint per level in settings. Rejected: settings keyed by level name is a table with extra steps, and it gives no place for per-level dimensions or ordering.