Imaginaria Worlds

All educational content lives in 7 structured JSON files at src/content/worlds/. Each world — Space Mission, Deep Ocean, Dinosaur Discovery, Dragon Tales, Enchanted Castles, Jungle Expedition, Mystic Mountains — defines a complete data tree: slug, title, order, art paths per mode, intro/outro narrations, media references (video, audio, art), and a nested array of topics containing quests. Each quest carries a question with kids/tweens variants, multiple-choice options with per-option audio, correct/incorrect feedback, media for each flow step, and sound effects. Every world supports two age modes — Kids ("Little Explorers") and Tweens ("Epic Adventurers") — with completely separate narration text, artwork, and videos per mode. A listWorlds() server function reads these files at runtime using Node.js fs, sorts by order, and supports slug aliases for backwards-compatible URL routing.

Key Details

The app guides children through a carefully designed progression. It starts at the landing page with an emerald gradient and Leo the astronaut character, then flows through a language picker (6 languages with flag icons), world selection (filterable by age mode), world landing with intro video and narration, quest selection with progress badges, the core quest flow (Watch → Read → Answer → Celebrate), and finally a world completion page with score summary and rating. Each transition is intentional — checking localStorage for language preference before routing, hiding the navigation header entirely during quests for immersive mode, and firing confetti on correct answers. The quest flow is the heart of the experience: a looping video builds context, tappable narration text teaches vocabulary, multiple-choice tests comprehension, and streak celebrations reward consistency.

Key Details

This is the technical heart of the app. The /api/translate route implements a priority waterfall for every word tap. Tier 1 checks the quest_narrations word map — a curated, context-aware, per-quest dictionary stored as JSONB in Supabase. This is the highest-quality translation because it knows that "trunk" means "tree trunk" in a jungle quest, not "car trunk." Tier 2 falls back to the word_translations table — cross-world vocabulary overrides for consistent translations of recurring words. Tier 3 falls back to Google Translate's free endpoint (no API key needed) for any word not yet curated. The same cascade applies to full narration translation via the POST variant — checking quest_narrations.text_[lang] before falling back to Google Translate sentence by sentence. This means the app works immediately for any word in any language, but the quality improves over time as translations are curated through the admin workspace.

Key Details

A full-screen dark CMS at /admin/translations for curating all translations that power the Tier 1 and Tier 2 systems. The left sidebar lists all quests grouped by world with a live search filter. Selecting a quest loads its data into the right panel, which has four controls: a Kids/Tweens mode toggle (switching which narration variant is being translated), a language selector with six flag icons, a translation text area with a "Google Translate ✨" button for auto-populating then manually correcting translations, and a word map editor showing every unique English word from the narration as an editable row with its current translation. Common grammatical words (a, the, is, are) are pre-marked as null (skipped). A "Generate from text" button auto-populates the word map via positional alignment between English and translated word lists. On save, everything upserts to quest_narrations using the composite key (world_slug, quest_id, mode).

Key Details

No login, no email, no password. Users are identified by a memorable 3-part adventure code (WORD-WORD-0000) generated at profile creation and stored in localStorage. The /welcome page lets users pick a name (max 20 chars) and choose from 16 avatars (8 kid-style, 8 tween-style characters). On submit, createProfile() inserts a row into Supabase profiles and returns the adventure code. The /profile page shows avatar, name, score, daily streak badge (active fire or dormant), a 3-stat grid (words learned, worlds explored, quests done — all derived from user_vocabulary), and the adventure code as a copyable button. Below the stats sits the VocabularyBook component — a scrollable list of all tapped words grouped by world with a language-switcher to view translations in any of the 6 supported languages.

Key Details

The gamification system runs on two tracks — localStorage for quest-level progress and Supabase for persistent streaks. Correct answers award 10 points, a 3+ answer streak adds 5 bonus points, world completion gives 25 points, and a perfect world (all first-try) gives 50 points. Quest progress (completed, first-try success, score 1–3, attempts) is stored in localStorage under keys like worldProgress:kids:space-mission. The daily streak is stored in Supabase profiles (streak_count and last_quest_at) so it persists across devices. The StreakCelebration component fires on quest completion — showing a flame banner if the streak is 2+ days, with canvas-confetti for visual reward. Every correct answer triggers an SFX, incorrect answers allow retry, and the celebrate step uses Framer Motion for smooth transitions.

Key Details

Four PostgreSQL tables in Supabase power the entire backend. profiles stores user identity (adventure code, name, avatar, score, streak_count, last_quest_at, native_lang). quest_narrations is the curated translation table with a composite key (world_slug + quest_id + mode) — it stores the original English text, full translated narrations per language (text_cs, text_de, text_es, text_fr, text_it, text_pt), and JSONB word maps per language (map_cs through map_pt) mapping each English word to its context-aware translation. word_translations is a cross-world vocabulary override table (word_en, world_slug, lang, translation) used as Tier 2 in the cascade. user_vocabulary records every word a user has tapped — with upsert logic incrementing times_seen on repeat taps of the same word.

Key Details

Videos are hosted in a Supabase Storage bucket (imaginaria-videos) organised by world with per-mode variants (kids-intro.mp4, tweens-intro.mp4, per-quest videos). These are referenced via direct Supabase CDN URLs embedded in the world JSON files. Audio files (MP3 narration) and images (JPG/PNG artwork) are served from Vercel's static file system under /public. Four Python upload utility scripts in the repo root handle batch media operations: uploading from the local filesystem to the Supabase bucket, batch compression, and direct upload. The split approach keeps the most bandwidth-heavy assets (video) on Supabase CDN while keeping smaller assets (audio, images) fast and simple on Vercel's edge network.

Key Details

Seven API routes power the app: GET/POST /api/translate for the 3-tier translation cascade (GET for single words, POST for full narrations), GET /api/worlds and /api/worlds/[slug] for world data, GET /api/quests/[id] for quest data, GET /api/health as an unprotected health check, and dev-only debug endpoints. The entire app runs behind a beta gate — middleware.ts checks a BETA_PASSCODE environment variable and protects all routes except health checks and static assets. Access is unlocked via a ?beta=CODE query parameter (sets a 30-day httpOnly cookie) or an existing cookie. Unauthenticated requests see an inline HTML gate page with a passcode form — no external assets needed. PWA support is configured via a Web App Manifest with apple-mobile-web-app-capable metadata and a service worker registration component.

Key Details

The visual identity is built around emerald green (#10b981) — evoking nature, adventure, and calm learning. The landing page uses an emerald gradient with a glow-pulsing "Let's Go!" button and Leo the astronaut as a friendly guide character. World cards display mode-specific cover art in 3:4 aspect-ratio tiles with inner glow borders. The AppHeader renders a three-item bar (LanguageSelector, Logo, HamburgerMenu) and reads usePathname() to return null entirely on /quest/* routes for full immersive mode. The HamburgerMenu provides navigation to Choose, Profile, About, Feedback, and conditionally Admin. All quest flow transitions use Framer Motion for smooth step changes. The app is fully responsive with Tailwind CSS v4 utility classes throughout.

Key Details

Reflection

What this project taught me

Imaginaria Worlds is the project that turned me from someone who builds websites into someone who builds products. The difference is enormous. A website has pages. A product has systems — and those systems need to work together, evolve independently, and serve users who will never read a single line of your code.

The 3-tier translation cascade was the biggest architecture lesson. Designing a system where quality improves progressively — from automatic Google Translate on day one to fully curated context-aware translations over time — without any code changes or redeployment, taught me to think in layers. Every hard problem in this project was solved by adding a layer, not by replacing what was already working.

Building the admin workspace taught me that the tool you build for yourself is just as important as the tool you build for users. A bad admin interface means you stop curating content. A good one means you open it every day and the product gets better without writing code.

And designing for children — the most honest users in the world — taught me that if something is confusing, they simply leave. No polite feedback, no workarounds. That discipline shaped every UX decision: progressive disclosure, minimal text, visual rewards, and a flow that never asks a child to make a decision they don't understand.

Skills Demonstrated