Data Contracts

Data Contracts

Big Rule

runtime data lives under /data.

repo intent:

• /data is not supposed to be versioned normally
• .gitignore ignores /data/**/*
• .rsyncignore excludes /data/** from deployment sync

so local/dev/prod data has to be managed separately.

data/accounts/

accounts.json

expected top-level shape:

{
  "accounts": [
    {
      "username": "string",
      "name": "string",
      "password": "bcrypt-hash or empty",
      "isAdmin": true,
      "mustResetPassword": false,
      "discordUserId": "optional discord snowflake string",
      "allowedPages": ["feed", "journal", "comments"],
      "bookmarks": ["2026-01-01_12-00-00", "journal:12", "newsletter:2026-01-01"],
      "theme": "default|custom|theme-id",
      "glowIntensity": "none|low|medium|high",
      "mobileFriendlyView": true,
      "colors": {
        "bg": "#RRGGBB",
        "fg": "#RRGGBB",
        "border": "#RRGGBB",
        "subtle": "#RRGGBB",
        "links": "#RRGGBB"
      }
    }
  ]
}

notes:

• extra unknown keys can exist and are preserved by account/admin/edit
• bookmarks are the current source of truth for logged-in users
• bookmark ids currently use raw feed ids, journal:{id}, and newsletter:{id}
• theme: default uses the standard template and /style.css; theme: custom enables saved colors; any other valid value refers to a /themes/{theme-id}.json file
• mustResetPassword is used by the shared session bootstrap to force first-login password changes
• discordUserId links a site account to a Discord member for bot DMs and notifications
• allowedPages currently includes functional grants like feed, journal, and comments

/themes/

theme metadata lives as JSON files directly under /themes.

{
  "name": "Theme Name",
  "html": "template-file.html",
  "css": "stylesheet-file.css"
}

notes:

• the metadata filename is the saved theme id, for example /themes/cool.json becomes cool
• name is the label shown in /settings
• html and css must be relative paths in /themes/lib, for example aero/aero.html and aero/aero.css
• theme asset paths cannot be absolute, contain .., or use characters outside letters, numbers, ., _, -, and /
• desktop rendering uses both themed HTML and CSS
• mobile rendering keeps template_mobile.html and only swaps the CSS

login_attempts.json

• map of client IP -> unix timestamp array
• used for login throttling

data/feed/

feed post format:

1. @username
2. YYYY-MM-DD HH:MM:SS
3. body text / BBCode

other file:

• index.toml is generated by /feed/index.php

data/feed/replies/

per-post replies live in {postId}.json files shaped roughly like:

{
  "replies": [
    {
      "id": "20260413153000_deadbeef",
      "username": "toast",
      "date": "2026-04-13 15:30:00",
      "body": "reply body with BBCode"
    }
  ]
}

notes:

• reply ids are generated on write; older data may be normalized into legacy_* ids at read time
• reply bodies can contain image BBCode that points at /data/images/*

data/journal/

published journal post:

1. YYYY-MM-DD
2. title
3. description
4. trusted HTML body

draft format:

1. USER:<username>
2. title
3. description
4. optional FORMAT:html
5. draft body

without FORMAT:html, preview treats the body as BBCode. with it, preview treats the body as raw HTML.

data/guestbook/

entry format:

1. timestamp
2. display name
3. message body

plus:

• ip_index.json for one-post-per-IP ownership tracking

data/images/

• uploaded images used across feed, journal, gallery, and newsletter content
• expected web path is /data/images/<filename>

data/music/

artist folders currently include:

• frdg3
• cactile

album JSON shape:

{
  "album_name": "string",
  "album_caption": "string",
  "album_type": "Album|EP|Single|Remix|...",
  "album_art": "/data/images/example.jpg",
  "album_art_directory": "/data/images/example.jpg",
  "order": 6,
  "songs": [
    { "name": "Track", "directory": "/data/audio/file.wav" }
  ]
}

album_art_directory is preferred by current code.

data/audio/

• track files referenced by music metadata
• also used by shared playback features

data/newsletter/

• published newsletter bodies as {id}.html
• commonly date-shaped ids like YYYY-MM-DD

data/mdpaste/

• temporary markdown paste records as {id}.json
• ids are 16 lowercase hex characters
• records expire after 30 days and are cleaned up opportunistically on create/view
• unencrypted records store a markdown string
• encrypted records store only AES-256-GCM ciphertext plus PBKDF2-SHA256 salt/nonce/tag metadata; the password is never stored
• hard_breaks controls whether single paragraph newlines render as <br> instead of spaces

data/etc/

wip

• plain text maintenance flag

webhooks.json

used key:

{
  "discord_feed": "https://discord.com/api/webhooks/..."
}

toast.json

expected shape:

{
  "bot": { "token": "...", "client_id": "...", "status": "online|offline" },
  "stream": { "url": "http(s)://...", "name": "..." },
  "channel": { "id": "...", "name": "..." },
  "features": { "auto_play": true, "loop": true }
}

toast-updates.json

• array of timestamped bot status entries

toast-feed-notify-state.json

• internal bot dedupe state for sent feed mention/reply notifications
• stores which feed mentions and replies have already triggered DMs

toast-dm-history.json

• tracked inbound/outbound DM threads used by /others/toast-discord-bot/messages
• stores per-user profile snapshot data plus message history

off-topic-archive.json

• Discord export blob used by the archive viewer

page_views.json

shape is roughly:

{
  "pages": {
    "/": {
      "count": 12,
      "visitors": {
        "<sha256>": 1730931224
      }
    }
  },
  "updated_at": "2026-03-02T00:00:00Z"
}

data/downloads/

• downloadable binaries, archives, presets, and similar files linked from the site