week_2024/AGENTS.md

IKEA Foundation - Week 2026 Project

This project is a Ruby on Rails application developed for the IKEA Foundation. It is a multi-lingual, interactive game/educational tool where players progress through various stages, making choices or facing "chance" events.

Key Features

• Multi-lingual Support: Uses the mobility gem for translating content into numerous languages. Supported locales include: en, zh, hr, cs, da, nl, fi, fr, fr-CA, de, hu, it, ja, ko, nb, pl, pt, ro, sr, sk, sl, es, sv, uk.
• Hierarchical Content Management: A "Node" system (using ancestry) for managing pages, stages, and interactive elements.
• Player Progression: Tracks player progress, scores, and decisions across different stages in the Player model's progress JSONB field.
• Interactive Game Flow: Managed by GameController, featuring:
  • Stage: Presents a stage's answer nodes (good_answer, bad_answer, or chance).
  • Answer: Records the player's selection; for chance, an outcome child is sampled.
  • Stage result: Shows the outcome node and applies its score.
  • Last save / Results: Final compost-vs-landfill choice, then the scored results screen.
• Screen animation: Every screen swap is animated — CSS exits before the navigation, view transitions around the frame render, and a per-stage video that plays between an answer and the next stage. Mobile only. See below.
• Scoring: Answer scores live in config/question_scores.json, not in the database. See below.
• Analytics: An admin dashboard at /admin/:locale/analytics reporting funnel drop-off, answer distribution, the results-screen thumbs vote and who played — device, language and country. See below.
• Admin Interface: A backend for managing nodes, assets (Active Storage), users, and translations.
• Search: pg_search integration for content discovery.

Technical Stack

• Framework: Ruby on Rails 8.1.2
• Language: Ruby 3.4.9
• Database: PostgreSQL
• Asset Pipeline: Propshaft with Importmap-rails and Stimulus/Turbo.
• Background Jobs: Sidekiq with Redis.

Core Models

• Node: The central content model. Templates are hierarchy-dependent:
  • Root (Depth 0): start
  • Level 1: facts, intro, stage, last_save, results
  • Level 2 (answers under a stage): good_answer, bad_answer, chance
  • Level 3 (outcomes under a chance): good_answer, bad_answer
• Player: Tracks session state, progress (per-stage answer_id / result_id), the cumulative score, the scores hash keyed by food_waste, emissions, income, the furthest screen reached (furthest_step), the device class they played on and the results-screen thumbs vote (rating / rated_at).
• Asset & Attachment: Handles media and its contextual content (body text, styling) associated with nodes.
• User: Admin authentication and roles.

Scoring

Scores are not stored on nodes. config/question_scores.json holds them, and GameController#score_entry_for maps a node to its entry by position:

• stages[stage_index - 1].answers[answer.position - 1] for a normal answer.
• For a chance outcome, the parent chance node's entry is looked up the same way and the outcome is read from its outcomes[child.position - 1].

Each entry has an overall value (feeds player.score and the result band) and an impact hash of food_waste / emissions / income deltas (feed the per-category tones in GameHelper). type and early_exit are documentation only — nothing reads them.

Gotcha: because the mapping is positional, the JSON must mirror the node tree exactly. A chance answer needs a {"type": "chance", "outcomes": [...]} entry at its position; if it is flattened into sibling entries instead, the outcome lookup silently returns nil and that branch scores nothing. Verify with a bin/rails runner walk of the tree after editing.

Result band consistency guard

The two axes can diverge: a good chance outcome gives only overall: 1 where a safe good answer gives 2, so a player can accumulate green impact but a low overall — and land a "close call" headline above three positive impact texts.

GameHelper#result_state therefore raises the band from overall to at least GameHelper#tone_floor, computed from the same impact_tone values the impact texts use: all three positive floors at :best, none negative floors at :balanced. The guard only lifts, never lowers — a high overall still reaches :best, and any negative metric still allows :worst. The early-exit / last-save branch returns before the guard and is unaffected.

Consequence: the headline and the three impact texts are no longer independent. Retuning impact values in question_scores.json can move the headline even when overall is untouched, and changing IMPACT_TONE_BANDS changes both the texts and the band floor.

Results copy

Each impact category needs three distinct tone strings — positive, neutral, negative under game.results.<category> — in all 24 locale files. A missing tone is easy to miss because nothing raises: neutral was a verbatim copy of positive in every locale, so an income: 0 player was told they "earned some money". When touching these, sweep all locales and check the three strings actually differ, not just that the key exists.

Analytics

There is no event log. GameAnalytics derives everything from columns on players:

• progress — what people did (the answer node they landed on for each stage).
• furthest_step — where people stopped. Written by GameController#track_step, an after_action on the screen actions. Player#record_step only ever moves a player forward, so the browser back button can't rewind the funnel.
• device — what they played on: mobile, tablet or desktop.
• locale and country — who they are, feeding the two breakdown panels beside devices.

Step names are facts, intro, stage_<n>, stage_<n>_result, last_save, done, results, ordered by Player.step_rank.

Gotcha: stage reach is computed from progress, not by comparing furthest_step ranks. The last-save early exit jumps a player straight to the end of the game, so a rank comparison would credit them with stages they never saw. The last-save branch is therefore reported as its own panel rather than as a funnel step.

Gotcha: DemoActivity (see app/services/demo_activity.rb) invents players with no gameplay to feed the leaderboard banner, which inflates every count and shows up as a huge drop before "Facts". The dashboard warns about this while DemoActivity::ENABLED is true.

Device

Player.device_from_user_agent classifies the User-Agent once, when GameController#start creates the player; there is no client-side probe and nothing re-checks it later. The match order matters — tablets are tested first, because an Android tablet's UA also says "Android" and only phones add a Mobi token, so a mobile-first test would swallow every tablet.

Crawlers and anything unrecognisable are stored as nil rather than falling through to desktop, and GameAnalytics#by_device drops nil rows — so the shares describe only the players we could actually place, and a bot run can't quietly pad the desktop column.

Known blind spot: iPadOS 13+ sends a desktop Safari UA by default, so some iPads are counted as desktop. Nothing short of client-side probing fixes it; the tablet share is a floor, not an exact figure. Players created before this column existed are nil forever — the UA was never stored, so there is nothing to backfill from.

Thumbs up / down

Player#rate! stores rating as 1 / -1 (Player::RATINGS), one per player — voting again overwrites. The results screen posts to game#rate via rating_controller.js, which flips the button state immediately and does not await the response.

Screens and animation

Every screen lives inside the single turbo-frame#game, so there is no page render to hang an animation off. Two mechanisms cover it: a class the outgoing screen puts on itself before navigating, and a view transition wrapped around the frame render.

All of it is gated to (max-width: 1023.98px) and (prefers-reduced-motion: no-preference), in the CSS and again in JS (TRANSITION_MEDIA in application.js, MOTION in answer_controller.js). Desktop and reduced-motion get the plain instant swap, so a new transition needs both halves of the gate or the two disagree — a JS-only gate leaves the browser's default cross-fade running on desktop.

Exits

start_controller#exit and answer_controller#exit add is-exiting to <main> when the CTA is tapped. The start screen animates while the facts modal is being fetched — the modal waits for the outgoing wave before it opens — and the answer screen holds its own navigation until the video is nearly over. The pattern is always the same: measure the block that has to leave, publish its height as a custom property, and let a negative margin free the space while a transform carries the block off-screen — --exit-shift for the answers container, --header-shift for the stage header (is-finishing, used only on the way to the results, where the video takes the whole screen). The hero is flex: 1, so it grows into whatever the margin releases.

Stage videos

Every stage node carries a video attachment beside its image. stage_result and done render it in the hero behind the copy at opacity: 0; the exit fades it up as the result copy slides away. answer_controller then holds the navigation until timeupdate reports less than --dur-base remaining, so the next screen assembles over the video's tail rather than after it — ended and a rejected play() are the fallbacks, and a stage with no video just navigates. The intro video is warmed up ahead of time by _preload_intro, a 1px preload="auto" element on the start and facts screens (the facts modal is appended over the start page, so that copy keeps buffering while the player reads).

Gotcha: the base .hero-container:has(video) rule (white text, shifted h2) is scoped to .intro. Unscoped, it silently restyles every result screen the moment a stage gets a video.

Transitions

SCREEN_TRANSITIONS in application.js maps "<from>><to>" — the template class the layout puts on <main> — to a transition name. A match overrides Turbo's event.detail.render so the frame swap runs inside document.startViewTransition(), with the name on html[data-screen-transition] for the CSS to key off. The current set: slide-left (whole screen from the right), slide-up (whole screen from the bottom, into the results), answer (hero cross-fade, options sink, result copy rises) and stage-in (header updates in place, video cross-fades to the stage image, answers slide up).

Anything that must animate after the snapshots are gone hangs off .is-settling, added to the new <main> when the transition finishes. Both waves use it.

Gotcha: a view-transition-name on a descendant cuts it out of its ancestor's snapshot, so the ancestor arrives with a transparent hole where it used to be. That is why the waves are hidden during the transition and animated afterwards on the real element instead of being named.

Gotcha: anything that overflows during a transition gives the scroller a scrollbar, and a scrollbar shrinks clientHeight. A wave sliding in from off-screen right did exactly that to the facts dialog and left a strip of panel showing under the hero. Clip the container (.carousel-frame, .hero-container while settling) and measure from getBoundingClientRect(), not clientHeight.

Gotcha: main.results paints no background of its own — body:has(.results) does — so its snapshot is transparent wherever a child does not paint. It gets an explicit background for the duration of slide-up, otherwise the video behind shows straight through it.

Gotcha: screen-slide-up travels 100dvh, not 100%. The results page is taller than the viewport, so 100% would start it a page-and-a-half down and travel that whole distance.

Gotcha: the results wave is rotate: 180deg, and transform composes after rotate — a transform-based slide arrives from the wrong side. wave-slide-in therefore animates the translate property, which is applied before the rotation and means the same thing on every wave.

The facts modal

start.turbo_stream.erb appends the dialog to body#page, outside the frame, so the intro can render behind it and the panel can then slide down to reveal it (modal#leave). Its CTA needs an explicit data-turbo-frame="game" for that reason. modal_controller#settle waits on one element's own transition — it filters out events from descendants and from ::backdrop, either of which would otherwise end the wait early.

The carousel wave is a single overlay in .carousel-frame, not one per slide, so it stays put while the slides scroll under it. It is positioned from --slide-copy-height, which carousel_controller#equalizeHeights publishes when it levels the slides.

Development shortcuts

DevJump (app/controllers/concerns/dev_jump.rb, development only) opens any screen directly instead of playing through: it creates a player on demand and back-fills the progress the screen expects, scoring it the way the real answer action would. ?dev=good|bad|chance|chance_bad starts a fresh player and answers the whole run that way; without it an existing session player is kept and only the gaps are filled, so a jump can be played on from. ?dev_last_save=1 also answers the last-save question. /:locale always clears the player, so the start screen looks like a first visit. The ⚡ panel bottom-left (shared/_dev_jump) links every screen; its links are _top full page loads so entrance animations replay from scratch.

Project Structure

• app/controllers/admin/: Admin backend logic.
• app/controllers/game_controller.rb: Main game loop (stage -> answer -> result -> results).
• app/controllers/api/: JSON endpoints (see docs/leaderboard_api.md).
• app/helpers/game_helper.rb: Result bands and per-impact tone thresholds.
• app/services/game_analytics.rb: Aggregates the admin analytics dashboard.
• app/controllers/admin/analytics_controller.rb: Admin analytics dashboard.
• app/controllers/concerns/dev_jump.rb: Development-only screen jumping.
• app/javascript/: Stimulus controllers for the game, flat (not under controllers/), each registered in application.js, config/importmap.rb and the layout's importmap tag list.
• app/models/concerns/: Shared logic for ancestry, attachments, and tags.
• config/locales/: YAML translation files.
• config/question_scores.json: Answer scoring table.