Bored.
Bored Backend — How The Button Would Work For Real
Right now this page is local-only — the pools live in POOLS in the browser, the button just cycles indices[currentCat]. This backend is the map to make it real: same channels, same button, but with server-side pools, moderation, favorites, history, and no repeats. Scripture is never edited by the backend — it is read-only, seeded once, and locked.
01 / Files to create
api/bored/channels.php GET /api/bored/channels api/bored/items.php GET /api/bored/items?channel=jokes api/bored/next.php GET /api/bored/next?channel=jokes (server-side rotation) api/bored/submit.php POST /api/bored/submit api/bored/moderate.php POST /api/bored/moderate api/bored/favorites.php GET /api/bored/favorites / POST /api/bored/favorites api/bored/history.php GET /api/bored/history api/bored/vote.php POST /api/bored/vote api/bored/report.php POST /api/bored/report sql/bored_tables.sql
Keep the tinyfiles PHP pattern: each endpoint loads /api/bootstrap.php, uses json_in() / json_out(), member session for auth where needed, prepared PDO statements. Public read endpoints can be anonymous; write endpoints require member session.
02 / Database tables
-- sql/bored_tables.sql
bored_channels
slug VARCHAR(32) PRIMARY KEY -- scripture, stoicism, jokes, dadjokes, programmer, tinyfacts
label VARCHAR(60) NOT NULL -- "Real Scripture", "Dad Jokes", etc.
sort_order INT NOT NULL DEFAULT 0
is_locked TINYINT(1) NOT NULL DEFAULT 0 -- 1 = scripture, never edited via API
created_at DATETIME
bored_items
id CHAR(36) PRIMARY KEY
channel_slug VARCHAR(32) NOT NULL
text TEXT NOT NULL
source VARCHAR(120) NOT NULL
status ENUM('pending','approved','rejected','retired') NOT NULL DEFAULT 'pending'
submitted_by VARCHAR(80) NULL
approved_by VARCHAR(80) NULL
created_at DATETIME
approved_at DATETIME NULL
FOREIGN KEY (channel_slug) REFERENCES bored_channels(slug)
bored_item_votes
member VARCHAR(80) NOT NULL
item_id CHAR(36) NOT NULL
vote TINYINT NOT NULL -- +1 funny / -1 not funny
created_at DATETIME
PRIMARY KEY (member, item_id)
bored_favorites
member VARCHAR(80) NOT NULL
item_id CHAR(36) NOT NULL
created_at DATETIME
PRIMARY KEY (member, item_id)
bored_history
member VARCHAR(80) NULL -- NULL = anonymous, stored by session id hash
session_hash CHAR(64) NULL
channel_slug VARCHAR(32) NOT NULL
item_id CHAR(36) NOT NULL
seen_at DATETIME
INDEX (member, seen_at)
INDEX (session_hash, seen_at)
bored_reports
id CHAR(36) PRIMARY KEY
item_id CHAR(36) NOT NULL
reporter VARCHAR(80) NULL
reason VARCHAR(255) NOT NULL
status ENUM('open','reviewed','removed') NOT NULL DEFAULT 'open'
created_at DATETIME
bored_channels.slug = 'scripture' has is_locked = 1. The API must reject any POST that tries to create / edit / delete items in that channel. Seed it once from the exact KJV text already in this page, then lock it.03 / API endpoints & request flow
GET /api/bored/channels
- returns all channels + counts, in sort_order
- { "ok": true, "channels": [ { "slug": "scripture", "label": "Real Scripture", "count": 4, "is_locked": true }, ... ] }
GET /api/bored/items?channel=jokes&limit=20&offset=0
- returns approved items only for that channel
GET /api/bored/next?channel=jokes
- server-side rotation: picks next approved item the user hasn't seen in this session
- uses bored_history to avoid repeats, falls back to random when all seen
- returns { "ok": true, "item": { "id": "uuid", "text": "...", "source": "PG-13 Joke" } }
POST /api/bored/submit
{ "channel_slug": "dadjokes", "text": "...", "source": "Dad Joke" }
- validates channel exists, channel is NOT locked, text length 10..500, source length <=120
- creates bored_items with status = pending, never auto-approves
POST /api/bored/moderate
{ "item_id": "uuid", "action": "approve" | "reject" }
- moderator bearer token only, sets status + approved_by + approved_at
POST /api/bored/vote
{ "item_id": "uuid", "vote": 1 | -1 }
- member only, upsert into bored_item_votes, recalculates item score
POST /api/bored/favorites
{ "item_id": "uuid", "action": "add" | "remove" }
- member only, idempotent
GET /api/bored/history
- returns last 50 seen items for current member / session
POST /api/bored/report
{ "item_id": "uuid", "reason": "offensive / wrong attribution / duplicate" }
04 / Rotation & no-repeat logic
// Server owns rotation. Browser submits intent only. 1. GET /api/bored/next?channel=jokes 2. Server: SELECT * FROM bored_items WHERE channel_slug = ? AND status = 'approved' 3. Server: LEFT JOIN bored_history ON item_id WHERE member/session NOT seen 4. If unseen list is non-empty, pick one (ordered by least-seen, then random) 5. If all seen, clear history for that channel/session and start over 6. INSERT into bored_history (member/session, channel, item_id, seen_at) 7. Return item // Front-end keeps current behaviour as fallback: - If API is down, use local POOLS + indices (current code) - If API is live, replace feedItem() with fetch(/api/bored/next) - Never show a pending / rejected item
Why server-side? The browser version cycles in order and repeats quickly. Server-side with history gives you “never the same joke twice in a session” and lets you weight by votes later.
05 / Content rules — what can go in each channel
scripture: READ-ONLY. Exact KJV text only, source = "Book Chapter:Verse (KJV)". No edits, no paraphrase, no AI rewrite.
stoicism: Public domain quotes only. Source must be real author (Marcus Aurelius, Seneca, Epictetus). No fake quotes.
jokes: PG-13, clean, no slurs, no sexual content, no punching down. Classic setup/punchline.
dadjokes: Groan-worthy, family-safe, pun-heavy. If it makes you groan, it qualifies.
programmer: Real programmer jokes. Must be understandable to a non-programmer OR have a one-line explanation in source.
tinyfacts: Must be true and checkable. Source must be specific ("Tiny Fact" + fact origin in text if needed). No urban legends, no "studies show" without a study.
// Validation on submit:
- text 10..500 chars, no URLs, no HTML, no profanity list
- source 1..120 chars, no empty source
- duplicate check: same normalized text (lowercase, no punctuation) already exists -> reject as duplicate
06 / Moderation queue
1. User submits -> bored_items.status = pending, visible only to moderators 2. Moderator reviews in /admin/bored-queue (not in this page) 3. Approve -> status = approved, appears in GET /api/bored/next 4. Reject -> status = rejected, never shown, submitter can resubmit fixed version 5. Report -> bored_reports.status = open, item stays live until moderator reviews - 3+ reports auto-flags item for priority review, does NOT auto-remove 6. Retire -> status = retired, kept for history but no longer served // Moderator auth: - Same moderator bearer token pattern as other tinyfiles admin endpoints - Log every moderate action: who, what, when, old status -> new status
07 / Favorites, history & voting
// Favorites (member only)
- Heart button on output-box -> POST /api/bored/favorites { item_id, action: add }
- GET /api/bored/favorites returns favorited items, newest first
- Front-end: show "★ Favorited" state, allow unfavorite
// History (member + anonymous)
- Every GET /api/bored/next writes to bored_history
- Anonymous users: session_hash = sha256(session_id + channel), no IP, no fingerprint
- History is used only to avoid repeats, never for profiling
// Voting (member only, optional)
- 👍 / 👎 on output-box -> POST /api/bored/vote { item_id, vote: 1 | -1 }
- Score = SUM(votes), shown as "87% found this funny" if votes >= 10
- Voting never changes rotation order by default — it only helps moderation
(future: weight rotation by score once you have 100+ votes per item)
08 / Caching, rate limits & abuse controls
Caching: - GET /api/bored/channels: cache 1 hour, purge on channel change - GET /api/bored/items: cache 5 min per channel, purge on approve/reject - GET /api/bored/next: NEVER cache, must be fresh per user/session Rate limits (nginx, same as existing API): - /api/bored/next: 60 / min per IP/session - /api/bored/submit: 5 / hour per member, 1 / hour anonymous (or block anonymous submit) - /api/bored/vote: 30 / min per member - /api/bored/report: 10 / hour per member Abuse: - Profanity / URL / HTML filter on submit, before DB insert - Duplicate detection on normalized text - If a member has 3+ rejected submissions in 24h, cool down 24h - Reports are not public, reporters are not shown to submitters
09 / Front-end integration contract
// When API exists, replace feedItem() with:
async function feedItem() {
const res = await fetch('/api/bored/next?channel=' + currentCat);
const data = await res.json();
if (!data.ok) { /* fall back to local POOLS */ return; }
outputText.textContent = data.item.text;
outputSource.textContent = data.item.source;
}
// Channels come from API too:
GET /api/bored/channels -> rebuild #catGrid buttons from response
// Keep local POOLS as offline fallback only, so button still works if API is down.
// Recommended states: loading, live, simulation, empty, validation error, unauthorized, server unavailable.
// Never show a pending item as live. Never show a rejected item.
Seed script: php scripts/seed_bored.php reads the POOLS already in this page (scripture verbatim, plus the new dadjokes / programmer / tinyfacts) and inserts them as approved. Run once, then lock scripture.
10 / Seed & migration checklist
1. CREATE TABLEs from sql/bored_tables.sql 2. INSERT channels: scripture (locked), stoicism, jokes, dadjokes, programmer, tinyfacts 3. INSERT items: copy POOLS from this page verbatim, status = approved 4. VERIFY: scripture items match this page byte-for-byte, then set is_locked = 1 5. DEPLOY: api/bored/*.php, test GET /api/bored/next?channel=jokes returns a real item 6. SWITCH: front-end tries API first, falls back to local POOLS 7. MODERATION: create /admin/bored-queue, test submit -> pending -> approve -> live 8. CLEANUP: once live, keep local POOLS only as fallback, do not delete them