Skip to content

Database layout

The backend stores its state in SQLite databases and a small number of directories under the data/ tree.

Persistent files

  • data/data/database.db: item hierarchy
  • data/data/users.db: user accounts and roles
  • data/data/img/mapimgs/: map image files
  • data/data/img/descimgs/: description image files
  • data/backups/: ZIP archives created by the backup system
  • config/.env: runtime settings

Item database schema

The main items table contains these columns:

Column Type Description
placement_code TEXT PRIMARY KEY Unique identifier for the item. The root uses an empty string.
name TEXT NOT NULL Human-readable item name.
description TEXT Optional description text.
keywords TEXT Optional search keywords.
children_arrangement TEXT Layout hint for children. See Maps & Layouts.
self_alignment TEXT Layout hint for the item itself. See Maps & Layouts.
color TEXT Optional color value.

The database also includes an FTS5 virtual table named items_fts for full-text search.

User database schema

The users table contains:

Column Type Description
id INTEGER PRIMARY KEY Internal numeric user id.
username TEXT UNIQUE Login username.
password_hash TEXT Argon2 password hash.
role TEXT Role such as admin, maintainer, editor, or viewer.

Image storage

Images are stored as files rather than in the database. The backend writes uploaded images to the corresponding map or description image folders and serves them through the image endpoints.

Layout Hints

The backend stores layout hints in the children_arrangement and self_alignment fields. These values are saved as text in the database and interpreted as JSON by the frontend.

  • Cloud (Free) Layout uses relative points with normalized coordinates (where [0, 0] is top-left and [1, 1] is bottom-right). Example: {"type": "cloud"} for parent, {"type": "cloud_child", "relative_points": [[0.5, 0.5]]} for child.
  • Grid Layout defines rows, columns, top_left_corner, and bottom_right_corner. Child items specify their row and column. Example: {"type": "grid", "rows": 6, "columns": 3, "top_left_corner": [0.1, 0.23], "bottom_right_corner": [0.9, 0.77]} for parent, {"type": "grid_child", "row": 2, "column": 1} for child.