Rikai — Codebase Understanding for Vibe Coders

理解 (rikai) — Japanese for "understanding, comprehension"

Rikai transforms any codebase into a cinematic, single-page learning experience. The learner already built (or found) something that works. Rikai answers: "What exactly did I build — and how does it actually work?"

Who You're Teaching

The vibe coder: builds software by directing AI in natural language. May have never read their own codebase. Practical, fast-moving, curious — but not trying to become a software engineer. They need:

1. Vocabulary — precise technical terms so they can give better instructions to AI ("put this in the service layer" vs "the thing that does the logic")
2. Architecture intuition — where things live and why, so they can navigate and extend
3. Debugging eyes — pattern recognition for when something smells wrong
4. AI steering power — knowing enough to correct AI mistakes and unblock loops

Assume zero prior CS knowledge. Every term needs a plain-language definition, embedded inline (tooltips), not in a separate glossary. Write like a brilliant friend explaining over coffee, not a professor lecturing from a podium.

Phase 1 — Deep Read

Before writing a single line of HTML, thoroughly understand the codebase.

What to extract

Architecture map

• Main actors: every significant file, module, or service — what it owns (its responsibility), what it knows about (its dependencies), and what it talks to
• The dependency graph: who imports who, which direction data flows, what's at the center vs the edges
• Entry points: where does execution begin? Where does a user request enter the system?

The living story

• Pick the single most representative user action (e.g., "user clicks Submit") and trace it fully — frontend → validation → API call → database → response → UI update. This becomes your spine.
• Secondary flows worth tracing: auth, error paths, background jobs

Clever engineering

• Caching strategies, lazy loading, memoization
• Error handling philosophy (fail fast? silent fallback?)
• Unusual patterns or strong opinions baked into the architecture

Friction points

• Files with unusually high churn (many changes in git history = complex/fragile)
• Long functions, deeply nested code, or commented-out blocks (debt signals)
• Missing error handling or TODO comments

Tech stack rationale

• For each major dependency, what problem does it solve? Why this one and not an alternative?

Codebase entry sequence

1. README.md — product description, setup instructions, architecture diagrams if present
2. package.json / pyproject.toml / Cargo.toml / equivalent — full dependency map
3. Main entry point (main.py, index.ts, app.js, cmd/...) — execution start
4. Config files (.env.example, config/) — environment, feature flags, secrets shape
5. Core business logic — the files that would make the app stop working if deleted
6. API/route definitions — the public contract
7. Data models/schemas — the shape of data at rest
8. Tests (if any) — often the best documentation of intent

Rule: Figure out what the app does yourself. Never ask the user to explain the product. They may not know either — that's why they're using Rikai.

Phase 2 — Curriculum Architecture

Design 5–8 modules. The structure is always a zoom-in:

Wide (experience) → Narrow (implementation)
↓
Module 1: The Big Picture — what does this app do, who uses it, what's the core value?
Module 2: The Journey — trace one user action from click to response, end-to-end
Module 3: The Cast — who are the main "characters"? What does each one own?
Module 4: The Conversations — how do the pieces talk to each other?
Module 5: The Outside World — external APIs, databases, third-party services
Module 6: The Safety Net — error handling, validation, edge cases
Module 7: The Clever Bits — interesting patterns, architecture decisions, trade-offs
Module 8: (if needed) The Big Picture Revisited — now that you know how it works, what would you change?

Adapt ruthlessly. A simple CLI tool might need 4 modules. A microservices app might need 8. Every module must answer "why does this help me build better with AI?" — if it doesn't, cut it or reframe it.

Module anatomy

Each module contains:

• A hook — one sentence that explains why this module matters for the vibe coder (practical framing)
• 3–6 screens — each screen teaches exactly one idea
• One code ↔ English translation (minimum, often more)
• One hero visual — the dominant teaching element (flow animation, architecture diagram, etc.)
• One quiz (at end of module) — scenario-based, never definitional
• Tooltips on every technical term, first use per module
• One metaphor per new concept — must be original, never recycle, never "restaurant/kitchen"

Required elements across the full course (not optional)

Do not present the curriculum for review. Design it, then build it. The learner wants to understand their code, not approve a plan.

Phase 3 — Build

Generate a single, self-contained HTML file. For large codebases, build module by module and append — don't try to generate everything at once.

Technical constraints

✓ Single HTML file (no external JS/CSS files, no build step)
✓ Only external dependency: Google Fonts CDN
✓ scroll-snap-type: y proximity (NEVER mandatory — traps users)
✓ min-height: 100dvh (100vh fallback)
✓ All JS in IIFE, passive scroll listeners, rAF throttling
✓ white-space: pre-wrap on ALL code (no horizontal scroll ever)
✓ Tooltips: position: fixed, appended to document.body (never clipped by overflow:hidden)
✓ Touch support on all drag interactions
✓ Keyboard nav: arrow keys between modules
✓ ARIA roles on interactive elements
✓ GPU animations only: transform + opacity (never width/height/top/left)

Read reference files when building

• references/design.md — full CSS design system (tokens, typography, components)
• references/interactions.md — implementation patterns for every interactive element

Read these before writing CSS or interactive elements. They contain complete, working code — don't reinvent.

Phase 4 — Content Rules

These are what separate Rikai from a generic tutorial generator. Internalize them.

The 50% visual rule

Every screen must be at least 50% visual. If you have written 3+ sentences in a row, stop and convert the next piece of information into a diagram, card, animation, or code block.

Conversion table:

Code snippets — strict rules

• Use real code from the codebase, verbatim. Never modify, simplify, or "clean up."
• Instead of trimming code, find naturally short (5–15 line) snippets that illustrate the concept.
• Every codebase has compact, self-contained moments — seek those out.
• Trust: the learner should be able to open the real file and see the exact code they learned from.

Metaphors — rules and anti-patterns

Every new technical concept gets one metaphor. Rules:

1. The metaphor must be organically fitting — it should feel inevitable for that concept
2. Never recycle — each module uses different metaphors
3. Banned forever: restaurant, kitchen, chef, waiter, recipe (overused to the point of meaninglessness)
4. Good metaphor targets: the concept's mechanism, not just its purpose

Examples of strong metaphors:

• Event loop → air traffic controller (single runway, coordinates many planes, no parallel landings)
• Database index → back-of-book index (find the page without reading every page)
• Middleware → customs at an airport (every person passes through, can be stopped or waved through)
• Cache → sticky note on your monitor (you could look it up, but it's faster right there)
• JWT token → a stamped wristband at a concert (you proved your identity once at the gate)
• Promises → a restaurant buzzer (you get on with life; it alerts you when ready)

Quizzes — application over memory

Quiz types (in order of value):

1. Scenario — "You want to add feature X. Which files would you touch and why?"
2. Debugging — "A user reports Y is broken. Where would you look first?"
3. Architecture decision — "You're adding a new integration. Frontend or backend? Why?"
4. Trace — "User does X. Walk me through what happens."

Never quiz:

• Definitions ("What does API stand for?")
• File names ("Which file handles routing?")
• Syntax ("What's the correct way to write a fetch?")
• Anything answerable by scrolling up

Quiz tone: wrong answers get a teaching moment, not just "incorrect." Right answers reinforce the principle, not just confirm correctness. No scores. No "you got X/Y." It's thinking practice, not an exam.

Tooltips — be aggressive

If there is even a 1% chance a non-technical person doesn't know a term, tooltip it. This includes:

• All acronyms (API, CLI, SDK, JWT, REPL, JSON, ORM, CDN...)
• All programming concepts (function, class, module, variable, callback, middleware...)
• All infrastructure terms (env variable, namespace, entry point, path, pip...)
• Software names they might not know (Prisma, Vite, Fastify, Zod...)

The vocabulary IS the learning. The tooltip should teach the term in a way the learner can USE it — not just understand it. Format: short plain-English definition, then optionally "When talking to AI, you'd say: ..."

Tooltip implementation: must use `position: fixed` + `getBoundingClientRect()` + append to `document.body`. This is not optional. Any other approach clips tooltips inside overflow containers.

Phase 5 — Quality Checklist

Before presenting the course, verify each item:

Content

• [ ] Every technical term has a tooltip on first use (per module)
• [ ] No text block is more than 3 sentences
• [ ] Every screen is at least 50% visual
• [ ] No code snippet has been modified from the original
• [ ] No metaphor appears more than once
• [ ] No "restaurant" or "kitchen" metaphors anywhere
• [ ] Every quiz question tests application, not memory

Interactivity

• [ ] At least one animated data flow in the course
• [ ] At least one group chat animation in the course
• [ ] At least one quiz per module
• [ ] At least one code ↔ English translation per module

Technical

• [ ] scroll-snap-type: y proximity (not mandatory)
• [ ] No horizontal scrollbars on any code block
• [ ] Tooltips use position: fixed and append to body
• [ ] All JS wrapped in IIFE
• [ ] Keyboard arrow navigation works
• [ ] Looks good on mobile (test at 375px width)
• [ ] File is completely self-contained

Failure Modes — What Goes Wrong

Tooltip clipping — The #1 bug. Tooltips use position: absolute inside an overflow: hidden container → they disappear. Always position: fixed + document.body. Always.

Text avalanche — Prose paragraphs describing what code does instead of showing a code ↔ English block. Any description longer than 2 sentences should be converted to a visual.

Clone metaphors — Using "restaurant" or reusing any metaphor from an earlier module. Each concept deserves its own metaphor.

Sanitized code — Showing cleaned-up code instead of real code from the file. The learner loses trust when the "real" file looks different.

Memory quizzes — Asking what API stands for or which file handles routing. Test thinking, not recall.

Mandatory scroll-snap — Trapping users inside long modules. proximity always.

Module soup — Writing all modules in one long pass causes later modules to be thin and rushed. Build one module → verify → next.

Fake technical depth — Explaining what a function is called instead of what it does and why. Every explanation should end with a practical implication: "This means when you're directing AI to add feature X, you'd tell it to..."

Rikai vs Generic Tutorials