Skip to main content
    Norditco logo
    All engineering posts
    Published January 6, 2026Norditco Engineering

    Learn Persian with Sepideh: How the Web App, Android App, and Farsi TTS Fit Together

    • product
    • learn-persian
    • tts
    • architecture

    Learn Persian with Sepideh looks like one product to a learner. They find a lesson on the web, open the same course in the Android app, tap a phrase, and hear it spoken. Behind that experience there are four moving parts with four different jobs: a content backend that Sepideh edits, a Next.js web app, an Expo-based Android app, and a Farsi text-to-speech service built on Piper.

    This post explains how those parts fit together, why the boundaries sit where they do, and what we would tell another small team building a language product across more than one surface. It is an architecture walkthrough, not a changelog. We stay at the level of decisions and trade-offs, and we leave out hostnames, credentials and runbooks on purpose.

    Norditco is the publisher of the product, and norditco.com is the entity hub that lists it next to our other properties. The product itself lives at learnpersianwithsepideh.norditco.com, the Android app is on Google Play under the package com.ahmed_mansour_ouda.LearnPersianWithSepidehV4, and the speech tool has its own page at tts.norditco.com.

    The product problem

    Persian is a language where audio carries a lot of the teaching. The script is unfamiliar, transliteration only gets a learner part of the way, and short vowels are usually not written. A page of Persian text with no way to hear it is half a lesson.

    Three constraints shaped the system:

    1. The teacher is not an engineer. Sepideh writes courses, lessons, flashcards, articles and resources. Her workflow has to stay in a content tool, and a code deploy must never be required to publish a lesson.
    2. There are at least two client surfaces. The web app is how most learners arrive from search. The Android app is how committed learners study daily. They should show the same material without anyone maintaining two copies of it.
    3. Audio is expensive and repetitive. Synthesizing speech costs CPU. Lessons contain the same phrases again and again, and learners replay them dozens of times. We needed audio generation to stay inexpensive per repeat and tolerable when the host is idle.

    Each constraint maps to a boundary in the architecture.

    System context

    The diagram below shows the whole system and who talks to whom.

    Architecture diagram. Expand for a larger view with zoom.

    Three things are worth noticing.

    First, content has one writer and many readers. Both clients read from the same content backend. Neither client owns lesson data.

    Second, speech is a separate service, not a feature of either client. The gateway has no idea whether a request comes from the Android app or the public speech page. It accepts text, a language code and a voice model, and returns a WAV file.

    Third, identity is handled by a managed provider. Firebase Auth gives both clients the same account model, and we did not build login infrastructure of our own.

    Content: one backend, many readers

    The content backend is a WordPress installation exposing the REST API. That sounds unfashionable, and it is the right choice for this product. Sepideh already knows how to write in it, custom post types model the domain well (courses, lessons, flashcards, resources, articles), and a language parameter on every query lets the same backend serve more than one teaching language.

    The web app treats this backend as a read-only upstream and puts a thin, deliberately boring client in front of it. A single fetch helper owns the behavior every call needs:

    • A hard timeout on every request, so a slow upstream cannot hang a page render.
    • A small, bounded retry that only fires for network failures and server errors. A 404 or a 4xx is a real answer and is never retried.
    • A fixed delay between attempts, so a brief upstream blip does not become a thundering herd.

    The services built on top of it (courses, lessons, flashcards, resources) catch failures and return an empty list or a null instead of throwing. That is a product decision as much as an engineering one. When the content backend is unavailable during a build or a revalidation, we would rather render a page with an empty section than fail static generation for the whole site. A learner who lands on a lesson page that is missing a related-lessons strip has a slightly worse day. A learner who lands on a 500 has left.

    Server components do the fetching. They call the content services during render and rely on the framework's fetch caching with an hourly revalidation window. For a language-learning site this is the right freshness. A lesson published this morning appears within the hour, and the origin sees a small, predictable amount of traffic no matter how many learners arrive from search. A narrow proxy route exists for the few browser-side cases that need content, and it forwards only paths that start with a slash, with a short browser cache and a longer shared cache.

    The Android app reads the same backend, but its constraints are different. A phone is offline more often than a server is, so the app wraps content in an on-device cache with a version number and a time-to-live. It can return fresh data, return stale data while a refresh runs, or return nothing. A learner on a train with no signal still sees yesterday's lesson, and the app does not show an error screen for a problem the learner cannot fix.

    The lesson here is that one upstream does not mean one client policy. The web client optimizes for build stability and origin load. The mobile client optimizes for offline use. Both are correct, and they share nothing except the shape of the data.

    The web app

    The web app is a Next.js application using the app router, with server components for anything that mostly renders content and client components only where interaction demands them. Courses, lessons, articles, resources and the study map are server-rendered. Games and other interactive pieces are client components.

    That split is mostly about search. Learners find Persian lessons by searching for specific phrases, and a page whose primary content arrives in the first HTML response is a page crawlers can read. Each route exports its own metadata, and structured data describes the site and the product, so the page that ranks is also the page that accurately describes itself. The way we connect these pages to the wider Norditco property graph is covered in our discovery mesh write-up.

    One codebase, more than one brand

    The same application also serves a sibling brand for a different teaching language. Rather than fork the repository, we resolve a tenant from the request host in middleware and attach the result as a header. Everything downstream reads the tenant: theme tokens, UI strings, feature flags, SEO entries, and the teaching language that drives content queries.

    This is a small multi-tenant design with a deliberate limit. Tenants differ in configuration, not in code paths. Per-tenant feature flags, such as whether authentication or web ads are enabled, are merged with environment overrides, which gives operations a kill switch without a code change. Unknown hosts fall back to a default tenant, so preview deployments still render something sensible.

    The cost of this approach is that every new feature has to ask which tenant it is running for. The benefit is that a second language product shipped as a configuration file and some assets, with no second deploy pipeline to maintain.

    Learning surfaces

    The learner-facing product has more shape than a list of articles. Courses group lessons. Flashcards and games (a card swiper, a word-match game, a memory-flip game) reuse the same flashcard data. A topic map organizes the material in a fixed teaching order: alphabet, greetings, light grammar, travel, stories, culture. A study-with-AI page offers a prompt that makes a general-purpose assistant teach in Sepideh's voice and cite the site's lesson URLs, so learners who study with an AI chat still get pointed back to canonical lessons.

    State is split by how much it matters. Authentication and favorites live in a small MobX store backed by Firebase. Lesson completion, course progress and study activity live in browser storage, because losing them is annoying and not harmful, and keeping them local means the common path needs no account and no write to a server. Game state stays inside the game.

    Quality gates

    The web app ships with unit tests for the content services, brand registry and flags, plus Playwright tests for the main learner paths. One check script runs lint, tests, a production build and the end-to-end suite, because the failure modes of a content site are quiet. A broken canonical tag or an empty course list does not throw. It just loses traffic.

    The Android sibling

    The Android app is built with Expo and React Native. It is a sibling, not a wrapper. It uses native Firebase modules for authentication, analytics, crash reporting and saved data, an on-device key-value store for caching, and a native audio player for speech.

    Two contracts keep the sibling honest.

    The first is a written backend contract. It describes which content endpoints the app depends on, which fields it relies on, and what is stored in the user's saved data. It states a policy that matters in practice: additive changes are fine, but renaming a path, removing a field, or changing the meaning of a saved-data key requires explicit maintainer approval and a migration plan. This exists because mobile apps have a long tail of old versions. A web deploy reaches every user in minutes, and an app release does not. If we break a field a shipped app depends on, learners on the old version see it break and we cannot fix it for them.

    The second is the shared content shape. Because both clients read the same backend, a lesson added by Sepideh appears in both, and neither client needs a release to show it. The teacher's publish button is the only deploy step for content.

    The app adds things a phone does better than a browser: study reminders, daily short-form content, and, most relevant here, tap-to-hear audio.

    Speech: the Farsi TTS service

    Speech is where the product system has the most interesting engineering, and where the boundaries pay off most.

    Why a separate service

    We could have shipped a text-to-speech library inside the Android app. We did not, for three reasons.

    Voice models are large, and bundling them would inflate every app download for a feature a learner uses in short bursts. Piper is a neural voice engine that is fast for its quality, but it is still model inference, and running it on a mid-range phone would cost battery and add latency. And the public speech tool already needed a server-side generator, so a second engine inside the app would mean two systems to keep sounding the same.

    A shared service means one voice, one place to improve pronunciation, and one cache that benefits every client.

    Request path

    The lifecycle of a single speech request is short, and every step exists for a reason.

    Architecture diagram. Expand for a larger view with zoom.

    The gateway does four things worth describing.

    It validates early. A request needs text, a language code and a voice model identifier, and the text is capped at 5000 characters. Bad input gets a 400 before any expensive work starts. Failures downstream are mapped to meaningful statuses: an unreachable or failing synthesis engine is reported as a gateway-style error, and a cache write failure or empty output is reported as a server error. The client can tell the difference between "you sent something wrong" and "we are having a bad moment".

    It derives a deterministic cache key. The key is a SHA-256 hash of the text, the language and the voice model, joined with a separator that cannot appear in normal text. Changing any of the three produces a different key, so switching voices never serves stale audio from the old one. The cache is a filesystem layout sharded by the first characters of the hash, which keeps any one directory small as the cache grows.

    It serializes work per key, and only per key. Two simultaneous requests for the same phrase are common. Think of two learners opening the same lesson after a newsletter goes out. A per-key lock means the first request synthesizes the audio and the second waits, then finds the file and returns it without touching the synthesis engine. Requests for different phrases take different locks and run in parallel. The lock is held on disk instead of in memory, so it survives a process restart and the double-check after acquiring it is always against the real state of the cache.

    It streams. Audio is moved through the gateway as a stream with backpressure, not buffered whole. Large inputs do not balloon memory, and a slow client does not force the service to hold the entire file.

    What the cache is really buying

    The cache is the single most important cost control in the speech path. Lesson content is finite and repetitive. The set of phrases a beginner course asks learners to hear is small compared to the number of times they will be played. After the first learner triggers a phrase, every later request for it is a disk read.

    That changes the shape of the cost curve. Synthesis cost scales with the number of distinct phrases in the content, not with the number of learners or replays. Adding a thousand learners to a lesson adds almost no synthesis work.

    It also changes how we think about cold starts. The speech service runs on demand on a shared VPS, which means the synthesis side may be idle when a request arrives, and the first uncached phrase can be noticeably slower than a repeat. We accept that on purpose, because it keeps a small product affordable. The cache makes the cost of that choice small in practice: the phrases most learners need first are the phrases that have been heard before.

    Pacing belongs on the server and the client

    Learners need slower speech than native speakers use. We split that responsibility in two.

    Voice character and sentence pacing are configured on the synthesis side. They are part of what a given voice sounds like, and they are baked into the cached audio. This has one operational consequence we learned to respect: if the synthesis pacing settings change, the cache has to be cleared, or learners keep hearing the old audio. Cache invalidation is explicit.

    The slow "learner" mode is a client-side playback rate. The Android app offers a normal speed and a slower learner speed and applies the rate at playback time to the same WAV. Both modes share one cached file and one network request. We did not ask the server for a slower rendering because that would double the cache and the synthesis work for a difference a media player can produce for free. The rate is configurable, so we can tune it without changing the service.

    The app also keeps an in-memory cache of audio for the current session, keyed by language, voice and text. Tapping the same word five times in a row costs one network request, not five.

    Contracts at the edge

    The service contract is intentionally narrow: one generate endpoint, a health check, and a JSON body of text, language and voice model. The response is a WAV stream. That narrowness is what let the implementation change underneath without client changes. The module has existed as a gateway that delegates to a separate Piper container and as a variant that invokes Piper directly, and the client contract stayed the same in both.

    Voice selection is a client setting with a sensible default. The app asks for a voice by identifier, and an unknown identifier produces an error instead of a silent wrong voice.

    The public speech page for the tool is a landing page. The generation endpoint is an application API and is not something we want crawled or indexed, which is a distinction we make explicit across Norditco properties.

    What the web app does and does not do with speech

    It is worth being plain about the current state. Today the Android app is the main consumer of the speech gateway in the learning flow, and the public Farsi TTS page is the other consumer. The Next.js web app focuses on reading, courses, games and the study map, and it does not call the speech service for lesson text.

    That is a deliberate sequencing choice and not a gap in the design. Audio in the app is a daily-study feature, where tapping a phrase is the main loop. On the web, many visits come from search and are short, and shipping audio there raises questions we want to answer with evidence first: autoplay policies, bandwidth on first visit, and how much a cold synthesis start affects a first-time reader.

    The architecture makes the next step straightforward. A web client would call the same endpoint with the same payload, would hit the same cache, and would sound identical to the app. The cache hit rate would improve because the phrases are already warm. The decision is a product one, not a technical blocker.

    Decisions we would repeat

    Keep content out of the code. The teacher publishes in a tool built for publishing, and a lesson goes live without a deploy.

    Make failure modes product decisions. A failed content fetch returns an empty section, a mobile read can return stale data, and a speech failure becomes a retryable tap. Each choice asks what the learner sees, not what the stack trace says.

    Treat speech as a product capability. A narrow contract, a deterministic cache key and per-key locking make it safe to add clients. Cost follows the size of the content, not the audience.

    Put the knob where it belongs. Voice and pacing live where the audio is made. Learner speed lives in the player.

    Write the mobile contract down. Web releases can be corrected in minutes. Mobile releases cannot.

    What we would improve

    The audio cache is a filesystem that grows with the content. It needs a retention policy and an inventory of which phrases lessons still reference. Pre-warming it when a lesson is published would remove cold-start latency for the first learner.

    Progress that lives only in browser storage does not follow a learner from web to phone. Moving it into account-level saved data is a contract change under our own rules, so we want to design the merge behavior carefully first.

    Takeaways

    A language product is a content system, a delivery system and a media system, and the best way to keep them from tangling is to give each one a narrow interface. Learn Persian with Sepideh gets that from a content backend with one writer, two clients with policies matched to their environments, and a speech service whose cost follows the size of the curriculum. The result is a small team that can add a lesson, a brand or a client without touching the other layers.

    If you want to see how Norditco's products relate to each other, norditco.com lists them in one place. If you want to hear the result, open a lesson on the web, then tap a phrase in the Android app.