MandarinAI

What it is, and what it proves

MandarinAI is for adults learning Chinese seriously: people who finished a beginner app and hit the point where flashcards stop being enough. It combines a spaced-repetition study loop with AI-generated graded reading, neural pronunciation and HSK-aligned word lists. One person designed, built and runs it.

Most apps keep flashcards and reading apart: you drill a character on Monday and meet it three weeks later in a story that treats it as new. MandarinAI connects the two, so the word you study and the word you read are the same word. For a buyer, it shows how we put AI inside a product's core loop and keep it dependable and affordable, rather than adding a chat box.

Product data that drives the AI

The base is spaced repetition on FSRS, the modern successor to the algorithm Anki made famous. Every word a learner studies has its own memory model (how stable, how difficult, how often it slipped), and each review updates it and schedules the next. Study time goes to the words about to be forgotten, not the ones already known.

That state is also the signal the rest of the product runs on. Because the app knows, per learner and per word, what is due, fragile or mature, it can do things a generic content app cannot.

Stories written from each learner's deck

Graded stories are generated from the learner's current spaced-repetition state: the exact words the scheduler says are worth reviewing now. A selector ranks the deck and hands the top words to the generator. Words due for review are candidates, but fragile words, reviewed before and slipping, rank higher, because a word you keep forgetting needs more exposure. "Fragile" means studied and slipping, never not yet seen, so brand-new words cannot crowd out the ones being lost.

The selection is deterministic, so it is testable and a given deck always produces the same explainable choice. Every story is built from words the learner half-knows, which keeps it between too easy and too hard, and every review feeds something to read.

AI output the app can rely on

Generation runs on Claude as structured output: the model fills a strict, typed shape (title, then sentences with Chinese, pinyin and an English gloss), so the app always receives something it can render directly instead of prose to parse. That contract is what makes AI content dependable enough to build features on.

There are several modes: plain reading, an interactive mode where the story branches on the reader's choices, and a fill-blank mode for active recall. A judge grades what a learner writes: a second model call scores the answer against a rubric and returns a structured verdict with feedback, instead of a naive string match.

AI spend kept under control

Generation costs money and time, so it sits behind an entitlements layer. Free accounts get a capped number of story generations per week, Pro removes the cap, and the checks live in one middleware layer rather than scattered through routes. The same layer gates the AI-teacher lessons (scenario dialogues generated to a chosen HSK range and length) while keeping already-generated content readable after a subscription lapses.

Audio is the other cost. Word and phrase pronunciation comes from a neural TTS model, and premium story narration uses a higher-quality voice. Every clip is cached in Cloudflare R2 by its content, so it is generated once and the next listener gets it from storage, and generation is rate-limited so nobody can run up the bill. Characters are drawn with animated stroke order and pinyin is rendered on the fly, so a word page is useful even before sign-up.

One Worker, maintainable by one person

The whole application is a single Cloudflare Worker. TanStack Start handles server rendering and routing, and a Hono app serves /api/* from the same Worker: one deploy, one runtime. Postgres is reached through Drizzle and Cloudflare Hyperdrive, so the edge gets pooled connections instead of a cold handshake per request. Auth is better-auth (email/password plus Google OAuth), billing is Polar, and product analytics run on PostHog.

There is no separate API service, no gateway to keep in sync, and no drift between frontend and backend repos. Types flow from the database schema to the React components in one codebase, so a change to the data model surfaces everywhere at build time.

A public reference site that brings in traffic

Much of the app is public on purpose: thousands of word pages, HSK lists across the old 2.0 and new 3.0 bands, idioms, songs with line-by-line pinyin, and "alternative to" guides, all server-rendered and indexable. Each page is useful on its own and also a landing page for a product where organic search is the main channel. Open Graph images are rendered per page so every URL shares cleanly.

The interface runs on a small in-house design system, "Ink & Vermillion", developed and documented in Storybook, with light and dark themes. It is the foundation that keeps a growing surface consistent when one person is maintaining it.

What a buyer should take from it

MandarinAI is live at mandarin-ai.com, built and run by one person. The value is the loop, not any single feature: a scheduler that knows what a learner is forgetting, a generator that turns those words into something worth reading, and an architecture lean enough for one person to keep running. Raw access to a language model does not give you that; the product engineering around it does.