Work/Bilingual reading app
Paralelo
A reading app that teaches Spanish and English through side-by-side stories, with every word linked to the word that translates it.
- My role
- Product, design, specification, direction and review
- Timeline
- October 13 to November 1, 2026: first prompt to Release 1.1
- Languages
- Spanish and English, in both directions
- Runs on
- Any browser, phone or desktop
What it is
Most language apps drill you. Paralelo lets you read. A story sits in two columns, aligned sentence by sentence. Point at a word and its partner lights up on the other side. Tap it and you get its dictionary form, its grammar and what it means in this sentence. Save it, and it comes back as a flashcard on the day you were about to forget it.
I designed the product, wrote the specifications and directed the build with AI coding agents, then had the result attacked by reviewers until nothing was left to find. The first working prototype was committed 64 minutes after my first prompt. Release 1.1 followed 19 days later.
This page is the long version of what happened in between, including the parts that went wrong. Sign-in was built twice. Three ways to import text were built and removed. The front page was redesigned and thrown away twice.
In numbers
- 64 minfrom the first prompt to a committed, working prototype
- 19 daysfrom the first prompt to Release 1.1
- 496commits, 86 of them on the busiest day
- 109,232lines of TypeScript, 42,524 of them tests
- 59database migrations, creating 49 tables
- 1,599unit test cases, plus 291 database tests and 139 end-to-end tests
- 46 of 46review findings that survived a second reviewer, all fixed
- 928 → 120 msone word tap on a 1,992-word story, on a throttled phone
Every figure on this page is counted from the project itself: its code, its history and its files.
How it was built
In the order it happened.
A prototype in 64 minutes
On October 13 I wrote one prompt describing a single self-contained page: a reader where the text is the hero, controls stay in a slim top bar, transitions are subtle, and nothing is gamified. Translations had to be written new, never copied from a copyrighted translation.
Sixty-four minutes later the prototype was committed: 32 texts, 330 sentence pairs, about 4,200 Spanish words, a dictionary of about 1,300 entries and about 14,000 generated verb forms. It worked offline. It was also a single file with no accounts, no database and no way to grow, which is why the next step was to rebuild it properly.
Rebuilt as a product, in seven gated phases
The next day I wrote a master prompt that fixed the role, the stack, the definition of done and the order of work, with a hard stop for my approval after every phase and an instruction to state risks and questions before writing code.
The rebuild landed in about four hours: 12 commits, 250 changed files. The first deploy served the host’s own 404 page, because the hosting project had been created for the old static file. That set the tone for the rest of the project: nothing counted as shipped until I had seen it running.

Tap any word: dictionary form, meaning in this sentence, tense and person, and how it sounds. Where the stories come from
Content arrives three ways. Classics: the app downloads a public-domain edition, verifies it, strips the library’s own text and cuts passages of 250 to 400 words, each published with its source. Originals: twenty stories written for the app, from A1 upward. Your own: paste any text and it comes back side by side, or give a topic and your saved words and a story is written at your level.
There is a new story every day with a short quiz, and every answer shows the line it came from.

Each story carries its level and reading time, from A1 originals to Aesop, Bécquer and Seneca. The hard core: which word is which
The whole product rests on one promise: point at a word and the right word lights up on the other side. Getting a language model to keep that promise across thousands of sentences was the hardest part of the build, and it is the first entry in the list of hard parts below.
The short version: asking a model for word positions fails quietly on long sentences. The links slip by one word, then chain, until a whole sentence is one color. The fix was structural, then a second model was brought in to check every pair, then every story already published was repaired.

When a word has no partner, the reader shows where it went: English “to” lives inside the “-ar” of “despreciar”. Grammar, in both languages at once
Grammar mode colors nouns, verbs, adjectives and adverbs, each with a different underline so color is never the only signal. A separate key marks word endings: who is acting, when, plural, gender.
An early audit rated this critical: translated words carried no part of speech anywhere in the pipeline, so someone learning English saw no grammar at all. It was fixed with rules written per language, down to details like “sees” being “see” plus “s”, not “se” plus “es”.

Grammar mode. Four word types, four colors, four underline styles. Saved words that come back on the right day
Every saved word keeps the sentence you found it in. Review is spaced repetition: rate a card Again, Hard, Good or Easy and it returns when you are about to forget it. Every verb opens into full conjugation tables, with a switcher that changes who and when and shows the word change inside real sentences.

Flashcards made from your own reading. Reviewed like somebody else’s code
I did not trust the build because I had watched it being built. Nine reviewers went through the app. Then a second reviewer was told to try to disprove every finding. Forty-six held: 24 high and 22 medium. All 46 were fixed, each by one agent and then attacked by another.
Security got the same treatment. Six auditors reported 20 issues, a skeptic disproved 2, and the remaining 18 were fixed with tests. In the three days around those reviews the project took 217 commits.
Shipping the last audit without breaking what was live
The final audit produced 18 database migrations that the previous release could not run under. So the order mattered: code first, then data. The migrations ship as one 1,563-line transaction that is safe to run twice, with a tested way back.
The first release build still failed on the host: a post-build check was looking in the wrong folder. It was fixed the same day, and that build was named Release 1.1.
The tour video is code too
The film at the top of this page is nine scenes rendered from code, in four cuts: English and Spanish, wide and vertical. It uses the app’s real palette, typefaces, stories and library covers, and the cursor aims at measured elements.
Every visual cue is pinned to a spoken word through word-level timings, and a check fails the build if a cue word is never spoken. The files are named “tour”, not “ad”, so ad blockers do not hide the section.
The hard parts
What broke, what was tried, and what finally held.
Word pairs that drift
- What happened
- The model returned bare word positions. On long sentences the links slipped by one word and chained until a whole sentence was one color. Cleaning up at display time and guessing neighbors did not hold.
- What fixed it
- Numbered word lists, links that name both the index and the word, shape checks before anything is saved, then a second model that asks of each pair: do these mean the same? A one-time repair then went through 36 stories and 560 sentences. 502 had a wrong pair. 5,857 links were removed and 1,552 added, without changing a word of any sentence. One agent repaired each story and a second verified it.
Words with no partner
- What happened
- Forcing every word into a pair produces lies: English “to despise” has no separate Spanish word for “to”.
- What fixed it
- An unpaired word now carries its reason (a verb ending, an omitted subject, a helper word, a contraction, an article, an idiom) and the reader shows it. One model kept slipping on these notes, and one slip failed a whole story, so that work moved to a stronger model.
Sign-in, built twice
- What happened
- Sign-in emails did not arrive. Code-and-link flows were built on one auth system, then replaced the same day by another, which shipped an error on log-in.
- What fixed it
- The audit traced it to sign-up tests that never ran in the automated checks. A dedicated job now runs them on every change.
Importing your own text: three dead ends
- What happened
- Video captions, then PDF upload including scans, then a text-file picker. Each was built. The first could not work from a cloud server at all.
- What fixed it
- All three were removed. Paste your text, and it is translated and aligned as a background job.
A front page redesigned and reverted, twice
- What happened
- Two full redesigns shipped and were undone. The second restore brought back copy with four claims that were no longer true.
- What fixed it
- The claims were corrected, and the standing rule stayed: every claim must be true of the product as built.
Cheap reasoning made bad word data
- What happened
- Everyday generation ran at the lowest reasoning effort to save cost. The word data it produced was not good enough.
- What fixed it
- Effort went to high everywhere and every story was written again, with three more fixes before the regeneration could finish on its own.
Jobs that outlived the platform
- What happened
- Long model calls ran past the page’s time limit and were cut off before saving.
- What fixed it
- A deadline on every call, and batch processing for the heavy work at half the price.
A reader that redrew every word on every tap
- What fixed it
- State moved outside the interface framework, one component per paragraph, off-screen paragraphs deferred. A tap on a 1,992-word story, on a phone profile slowed four times, went from 928 ms to 120 ms. Blocked time during read-aloud went from 4.5 seconds to 0.1 in a five-second sample.
Underlines that collide
- What happened
- Person, tense, plural, gender and saved-word marks all wanted the same strip under a word.
- What fixed it
- Each mark gets its own lane and the line height grows with the number of lanes, checked by screenshot sweeps from 390 to 1920 pixels wide and at 150% zoom.
Review scheduling out of order
- What happened
- Rating a card “Good” could bring it back sooner than “Hard”. On phones, dragging a card upward rated it “Easy”.
- What fixed it
- All four delays are computed together, and a test holds the order: Again, then Hard, then Good, then Easy.
A 150 KB budget with no slack
- What happened
- The build fails if the front page ships more than 150 KB of compressed JavaScript. The page sat at 149.8 to 149.9 KB. After a framework update it was 2 bytes under.
- What fixed it
- The budget stayed. Error pages were moved one level down in the route tree so their code stopped counting against the front page.
The rules I set
Written into the specifications before the code, and enforced after it.
- The text is the hero. Controls stay in a slim top bar.
- Every claim must be true of the product as built.
- Nothing should look templated.
- Implement every item and add a test or check for it. Mark it done only when its test passes.
- Security is layered so that no single mistake exposes user data.
- If something in this prompt conflicts with how the code already works, stop and ask instead of guessing.
How I worked
Prompts as specifications. Each stage began with a written document that fixed a role, a stack, the definition of done and the order of work, with a stop for my approval after each phase.
Audit, pick, fix, attack. Reviews came back as a page of findings with tick boxes. I chose what to fix. Fixes ran in parallel lanes, and every fix was checked by a second agent whose job was to break it.
What stayed in my hands: the product and its design, the prompts, the choice of which findings mattered, running the database changes, the accounts and keys, judging every screenshot, rejecting designs, and reporting what failed live.
On a simulated slow phone connection the front page scores 100 for accessibility, 100 for best practices, 100 for search, and 85 to 89 for performance.
Made with
- App
- Next.js 16, React 19, TypeScript, Tailwind CSS 4, Radix UI. Interface in English and Spanish.
- Data
- Postgres on Supabase, with row level security on every table.
- Accounts
- Clerk, with data export and account deletion built in.
- AI
- OpenAI models for stories, word alignment, definitions and read-aloud, with a second-model check on every word pair.
- Tests
- Vitest, Playwright and axe. A real Postgres boots for the database tests.
- Checks
- GitHub Actions with four jobs, a weekly dependency audit and code scanning.
- Video
- Remotion for the picture, ElevenLabs for voice and music.
- Hosting
- Vercel.