Tralala.cards

Conversation cards for groups. Next.js (App Router), no accounts. Ratings are backed by Vercel KV (Upstash Redis) — see below.

Run locally

npm install
npm run dev

Open http://localhost:3000 — it's designed for a phone, so use the device toolbar in your browser's dev tools.

Ratings require a KV store (see next section). Without one, /api/rate and /api/stats return a 503 and the "Most loved" screen just shows the seed percentages from lib/content.js — everything else works normally.

Ratings backend (Vercel KV)

1. Vercel dashboard → your project → Storage → Create Database → KV (Upstash Redis under the hood). Create it and connect it to this project — Vercel adds the KV_REST_API_URL / KV_REST_API_TOKEN env vars for you.
2. For local dev, pull those vars down: vercel env pull .env.local (requires the Vercel CLI, npm i -g vercel, and vercel link once first).
3. That's it — app/api/rate/route.js and app/api/stats/route.js read the env vars automatically via @vercel/kv.

Votes are stored as two Redis hashes (tralala:like, tralala:down) keyed by question index, plus one small hash per anonymous device id so a changed vote un-counts the old one first. No personal data is stored — just the device id already generated by lib/analytics.js.

Feedback board

The "SAY" screen lets players submit a short suggestion (500 chars max, one per device per day) and see + upvote/downvote what others wrote. It uses the same KV store as ratings, so it works automatically once that's set up — nothing extra to configure. Submissions are public to anyone using the app; there's no moderation beyond the daily limit, so remove anything inappropriate via the /moderate page (see "Admin" below).

Feedback export

Logged in as admin, open https://<your-site>/api/feedback/export in the same browser to get every submission as JSON.

Moderation

/moderate (linked from /admin) lists every submission with a DELETE button next to each.

Analytics

The app also tracks anonymous, aggregate-only product events — session starts, cards viewed (with question, category, language, and whether the category filter was left on "All" or narrowed), and shares — using the same device id and the same KV store as ratings and feedback. No personal data, no third-party analytics vendor; see lib/analytics.js (track()) for the client side and app/api/track/route.js for how each event turns into a few HINCRBYs. Every counter is day-bucketed (one hash per metric, fields shaped like "2026-08-28|fun"), so a reader can sum any trailing window instead of only ever seeing an all-time total.

Analytics export

Admin session only, like the feedback export:

1. Visit https://<your-site>/api/analytics for everything since launch, or add ?range=7 / ?range=30 / ?range=90 to scope sessions, views, and shares to that many trailing days (the sessions-per-day breakdown always comes back in full either way, so a caller can chart the whole history and still get lockstep totals for whatever window it's showing).
2. The response includes views.byCategoryByLang — card views broken down by category within each language (e.g. "what's popular among English players") — and views.byFilterMode — how often people browse with the category filter left on "All" versus narrowed to one or a few categories.

Insights dashboard

/insights (linked from /admin) is a private page that reads /api/analytics and /api/stats and renders them — sessions over time, new vs. returning, languages, categories (overall or filtered to one language), and question leaderboards (most seen, most loved, rarely loved). The 7D / 30D / 90D / MAX chips re-fetch /api/analytics for that window; the language chips just re-slice the single response already in hand. Like/down percentages are always all-time (that data doesn't live in /api/analytics) and only count questions with 3+ votes.

Admin

All owner-only pages sit behind one login (lib/adminAuth.js):

1. Set two env vars in Vercel (Settings → Environment Variables, Production) and redeploy:
   • ADMIN_KEY: a long random string (openssl rand -hex 24). It goes in the admin link: https://<your-site>/admin?key=<ADMIN_KEY>.
   • ADMIN_CODE: the code you type on that page. Make it long enough not to be guessed (a passphrase is fine).
2. Open the admin link, type the code. Each IP gets 3 wrong tries per 24 hours (key or code), then it is locked out until the 24 hours pass.
3. A signed, httpOnly cookie keeps you logged in for 12 hours in that browser. /admin then lists Insights, Moderation, promo codes and the owner mode of /create; "Atsijungti" logs out.

Without the session, every private page and API answers a plain 404, and all of them send X-Robots-Tag: noindex (next.config.mjs). They are deliberately not listed in robots.txt, which is public. Changing ADMIN_KEY or ADMIN_CODE logs every browser out. Leaving either unset switches admin off entirely.

Deploy to Vercel

1. Push this folder to a new GitHub repository.
2. vercel.com → Add New… → Project → import the repo.
3. Framework preset detects Next.js. Deploy.
4. Set up the KV store per the section above (before or after the first deploy — redeploy once it's connected so the env vars are picked up).

Every push to main redeploys.

Changing content — the only file you normally touch

lib/content.js holds everything: categories, all 150 questions in English and Lithuanian, every piece of interface copy, the card surfaces and category tints.

Add a question — append a row to Q:

['fun', 'English question?', 'Klausimas lietuviškai?', 50],

The fourth number is the like-rate shown on the "Most loved" screen as a fallback. Once a question has at least one real vote (via the ratings backend, see below), its live percentage is shown instead.

Add a category — add to CATS (id, en, lt, icon, optional note), add a hue to CAT_TINT, then write its questions. Adding it to OPT_IN keeps it out of the default deck (as with Spicy and Couples).

Change interface wording — edit UI.en / UI.lt.

Structure

app/layout.jsx          fonts, metadata, PWA manifest link
app/page.jsx            the whole app: home, deck, favourites, most loved, share, feedback
app/api/rate/route.js       POST one up/down vote, returns the question's updated tally
app/api/stats/route.js      GET aggregate tallies for every voted-on question
app/api/track/route.js      POST one anonymous product event (session/view/share)
app/api/analytics/route.js  GET the aggregated event counters (see Analytics below)
app/globals.css         resets and font variables — all other styling is inline
lib/content.js          ← all content
lib/deck.js             shuffle and deck-building
lib/analytics.js        anonymous device id, rating/stats fetch helpers, event tracking
public/manifest.json    PWA

Card surface

SURFACE at the top of app/page.jsx: 'Warm paper' (default), 'Ash grey', 'Category tint', or 'Ink card'.

Still to wire up

• Share as an image. The share screen currently uses the Web Share API with text. For the card as a picture, render the same layout through @vercel/og.
• Lithuanian proofing. The translations are a first pass — have a native speaker review, especially Spicy and Couples.

Icons & social preview image

app/icon.png, app/apple-icon.png, app/opengraph-image.png, and public/icon-192.png / icon-512.png are generated (not hand-drawn) — run node scripts/generate-icons.mjs to regenerate them if the brand colors or wordmark ever change. Uses the same Instrument Serif font as the app itself (font files live in scripts/assets/, fetched from Google's font repo).