DEV Community: Vadym Arnaut

4 footguns integrating YouVersion's new platform API — and a clean Verse of the Day

Vadym Arnaut — Fri, 15 May 2026 18:39:44 +0000

TL;DR. YouVersion opened its API in April 2026. We wired it into our open-source Bible LMS as a Verse of the Day card on the dashboard. Four small things in their API surface cost us time. Writing them up so you don't repeat them.

Equip is an open-source LMS for Bible schools (FastAPI + React + Supabase, MIT). A dashboard verse-of-the-day card is one of those quietly load-bearing features for a faith-shaped product — it gives the page a pastoral anchor on the right while keeping the actionable column primary, and creates a daily-return habit without screaming for engagement.

YouVersion just opened YouVersion Platform: 1,474 Bibles, 1,283 languages, REST API plus SDKs (Swift, Kotlin, React, React Native). Free for non-commercial use. So we plugged it in.

The endpoints are simple. The friction is in the small print.

Footgun #1: `/v1/bibles` returns 422 without `language_ranges[]`

First instinct after pip install httpx:

# Wrong. Will not work.
httpx.get("https://api.youversion.com/v1/bibles",
          headers={"X-YVP-App-Key": KEY})

Response:

HTTP 422 Unprocessable Entity
{"detail": [{"type": "missing",
             "loc": ["query", "language_ranges[]"],
             "msg": "Field required"}]}

The listing endpoint requires at least one ISO 639-3 language filter. We found that out the way everyone does — by reading the 422 body. Correct form:

httpx.get(
    "https://api.youversion.com/v1/bibles",
    params={"language_ranges[]": "eng"},   # eng, rus, ukr, etc.
    headers={"X-YVP-App-Key": KEY},
)

If you're calling from a JS client and reach for URLSearchParams, the brackets matter — language_ranges[] with the literal brackets works, language_ranges without them does not.

Side note while you're here: the auth header is X-YVP-App-Key, not Authorization: Bearer. The 401 you get from forgetting is generic enough that you'll sit there comparing your key character-by-character before going back to the docs. Pin the header name in the integration's docstring on day one.

Footgun #2: `all_available=true` reveals the real catalog

With language_ranges[]=eng,rus,ukr we got 11 Bibles back — all English (ASV, BSB, Geneva, CPDV, etc.). Zero Russian. Zero Ukrainian.

The marketing number is 1,474 translations. Where are they?

httpx.get(
    "https://api.youversion.com/v1/bibles",
    params={"language_ranges[]": "rus", "all_available": "true"},
    headers={"X-YVP-App-Key": KEY},
)

That returns 5 Russian Bibles: NRT (Новый Русский Перевод — the modern Russian we needed), three CARS variants, and CSLAV (church Slavonic). For Ukrainian: just UKRK 1905 — pre-revolutionary, hard for modern students. No modern Огієнко or UBIO in the platform yet.

The mental model: the listing endpoint without all_available shows what is enabled for your app key, not what exists in the platform. Fetching a passage via /bibles/{id}/passages/{ref} works for the broader catalog regardless of listing visibility — at least for non-commercial use as of this writing.

Worth two minutes verifying for your own keys before you build a UI that says "no Russian translations available." We almost did.

Footgun #3: `content` is HTML, even when you didn't ask

The passage endpoint is the cleanest part of the API. You hand it a Bible ID and a USFM ref:

GET /v1/bibles/143/passages/JHN.3.16
→ {
    "id": "JHN.3.16",
    "content": "<p>Ведь Бог так полюбил этот мир...</p>",
    "reference": "От Иоанна 3:16"
  }

Two things to notice. First, reference is localized to the Bible's language — "От Иоанна 3:16" for NRT, "John 3:16" for BSB, automatically. That is free i18n you would otherwise build yourself.

Second, content is HTML. Usually a thin  wrapper, sometimes with  markers, occasionally a chunk of whitespace bleeding from the source USFM. If you're rendering scripture in a plain-prose sidebar card, you have to strip:

def _strip_html(html: str) -> str:
    text = re.sub(r"<[^>]+>", "", html)
    # Some responses pack newlines inside <p> from the source markup —
    # collapse whitespace so the card renders as a single tidy line.
    text = re.sub(r"\s+", " ", text).strip()
    return text

YouVersion never injects user-supplied markup into content (it is their licensed text — they control the source), so a regex strip is safe here. Do not copy this pattern verbatim to places where the content origin is untrusted.

Footgun #4: their VOTD endpoint exists, but you cannot pick the verses

YouVersion ships /v1/verse_of_the_days/{day} that returns their curated verse for that day of year:

GET /v1/verse_of_the_days/135
→ { "day": 135, "passage_id": "ISA.12.2" }

Useful if you want to mirror the YouVersion app behavior exactly. But it is their selection — you cannot pass a tag, theme, or audience filter. For an LMS aimed at Bible-school students we wanted curated passages that bias toward doctrinally-neutral, evergreen, ecumenical scripture: no denomination-specific proof texts, nothing that translates badly into Russian or Ukrainian.

So we rolled our own list — 250 references covering salvation, hope, comfort, love, faith, wisdom, prayer, and perseverance. Grouped by canon section: Gospels, Acts, Pauline epistles, Hebrews and General epistles, Revelation, Psalms, Proverbs, Wisdom and Prophets, Torah and Historical books, Job and Minor prophets.

The shape that worked: deterministic by day, cached by day

Selection is a one-liner:

def _pick_reference(date: dt.date) -> str:
    """Everyone, everywhere, sees the same verse on a given UTC date."""
    return _VERSES[date.toordinal() % len(_VERSES)]

toordinal() gives a globally monotonic integer. Modulo the catalog size, you get a cycle that takes about eight months to repeat — long enough that no student sees the same verse twice in a school term. No randomness, no per-user state, no cache invalidation drama. The verse on a given date is the same in every browser on every device.

Cache is a process-local dict keyed on (date_iso, locale). Evict any entry whose date is not today on every write — the cache never holds more than len(supported_locales) entries. We support en and ru, so at most two entries deep:

with _CACHE_LOCK:
    for k in list(_CACHE):
        if k[0] != date_iso:
            _CACHE.pop(k, None)
    _CACHE[cache_key] = verse

Two YouVersion calls per Python process per day. If the API key is unset (CI, fresh local dev), the service raises a typed exception and the route returns 404. The frontend treats 404 as "hide the card silently."

Never block the dashboard on a third party. Same playbook as every other optional widget — but worth restating, because Bible-school students will not forgive a broken homepage on a Sunday.

A few things to weigh before you adopt this

Non-commercial lock-in is real. You agree at app registration. Future paywalls, ads, or paid tiers revoke API access. For an open-source LMS this is fine. For a commercial product, model around it on day one — your BibleProvider should be an adapter, not a hard import.
Russian coverage is solid, Ukrainian is sparse. Modern Russian is there (NRT). Ukrainian audiences still need a fallback layer for modern translations.
The SDKs ship UI components, not just data clients. If you're using their React SDK you may not need most of the integration code above. We chose the REST API because Verse of the Day in our app is server-cached and renders in a slot we already control.

What I'd ask the room

If you have integrated YouVersion Platform yourself — how are you handling the locale → bible_id mapping when there are multiple translations in the same language? We pick one per locale (en → BSB, ru → NRT) because Verse of the Day is a one-card, one-rendering surface. For a reading-plan flow where users want to switch translations on the fly the design space is wider — curious what others have done.

For anyone building Christian software in 2026 — does the non-commercial lock-in change how you architect, or do you accept it and never plan to monetize? Genuinely curious whether anyone has built around the constraint.

And for the YouVersion Platform team if you read this: an Accept: text/plain toggle on /passages would let consumers skip the strip-HTML dance. Probably trivial on your side, ergonomic win on ours.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Changelog

Why this project?

Hundreds of small Bible schools, home churches, and missionary training programs around the world still manage courses on paper, WhatsApp, or spreadsheets. Commercial LMS platforms are expensive, overkill, or require technical expertise that volunteer-run organizations simply don't have.

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not enterprise pricing models.
Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.

Features

Area	What you get
Course authoring	Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio)
Assessments	Multiple-choice, true/false, short-answer, and essay

…

View on GitHub

Two days lost to PGRST116: when Supabase RLS hides a successful write

Vadym Arnaut — Wed, 13 May 2026 19:36:01 +0000

TL;DR. Our Supabase upsert wrote the row. The chained .select().single() returned PGRST116. The wrapper read that as a failed write. The frontend retried. The retry was wrong. Two days to find why.

We've been running an LMS on Supabase for the past several months — auth, RLS on every table, FastAPI talking to Postgres. The bug below cost us two days last quarter, and the fix changed how we read PGRST116 in our wrapper.

The setting

We have a quiz_attempts table. Each attempt gets created on quiz start, updated as the student progresses. The update is an upsert because a retry of the same attempt_id should patch the existing row, not insert a duplicate.

const { data, error } = await supabase
  .from('quiz_attempts')
  .upsert({ id, student_id, quiz_id, attempt_count })
  .select()
  .single();

The .select().single() chain returns the upserted row so we can show the student their new state.

RLS policies, simplified:

create policy "students write their own attempts"
on quiz_attempts for all to authenticated
using (student_id = auth.uid())
with check (student_id = auth.uid());

create policy "students read their own attempts"
on quiz_attempts for select to authenticated
using (student_id = auth.uid() and is_visible = true);

The SELECT policy carries an extra is_visible check that the write policy doesn't. That asymmetry is the seam the bug walks through.

The bug

A trigger on quiz_attempts flips is_visible to false under a corner case (timing relative to a parallel write from an admin tool — the specifics aren't the point). The student's upsert committed: their fields were written, the row is theirs.

Then .select().single() runs. The SELECT policy applies. is_visible = false. PostgREST returns:

{
  "code": "PGRST116",
  "details": "Results contain 0 rows",
  "message": "JSON object requested, multiple (or no) rows returned"
}

Our runtime wrapper auto-threw on any .error. To the upstream code, this looked identical to a failed upsert. The frontend retried with the same payload. The retry hit the same trigger. The user state diverged from the DB state. Etc.

Why this was hard

PGRST116 has two completely different meanings when it comes after a mutation:

The upsert truly failed — constraint violation, missing required field, RLS denied the write.
The upsert succeeded — RLS just hid the returned row from the caller.

The wrapper conflated them. The PostgrestError code is identical. The HTTP status is identical (406). The only difference lives in the database, which the client can't see.

Two days of logs because we kept treating "no row returned" as "no row written."

The fix

Three changes.

1. Don't auto-throw on PGRST116 from a .select().single() chained off a mutation. Treat it as ambiguous and route to a separate branch:

async function safeUpsertReturning(query) {
  const { data, error } = await query;
  if (!error) return { data, error: null };
  if (error.code === 'PGRST116') {
    // The mutation may have succeeded; we just can't read the row.
    return { data: null, error: null, hidden: true };
  }
  throw error;
}

2. Service-role verification. When the wrapper returns hidden: true, the backend does a service-role read by id to confirm whether the row actually exists. Yes → success-without-readback (treat as written). No → real failure, propagate. The client never branches on this directly.

3. Observability tying client errors to DB state. Every PGRST116 from the wrapper emits a structured event with the query shape and request id. Server-side, we log the same id with the actual row state visible to service role. Correlating the two would have surfaced the mismatch on day one.

What I'd tell past-us

PGRST116 is not a write error. It's a visibility error.

Your wrapper, your error handler, your retry logic — each should know which one it's seeing. If your stack can't tell the difference, you're going to retry successful writes. The kind of bug that produces is the kind where the symptom and the cause are twelve layers apart.

What I want to hear back

Do you separate "write failed" from "write succeeded but I can't read it" in your Supabase code? What does the wrapper look like?
Has anyone built a Postgres-side audit trigger that captures "row was written but RLS hid it from the writer"? Curious about the shape.
For service-role verification — anything safer than select(*).eq('id', id) you've used?

The project that runs this stack is open source:

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Changelog

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not enterprise pricing models.
Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.

Features

Area	What you get
Course authoring	Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio)
Assessments	Multiple-choice, true/false, short-answer, and essay

…

View on GitHub

The 3 i18n mistakes every open-source LMS makes

Vadym Arnaut — Wed, 13 May 2026 03:21:32 +0000

TL;DR. Every open-source LMS treats internationalization as one problem. It's three. UI strings, user-generated content, and canonical artifacts each need a different mechanism. Most codebases collapse them into one — that's the bug.

We've been building an open-source Bible school LMS for about 5 months. It runs in Russian and English (Ukrainian coming), with auto-translated user content and canonical-text preservation for scripture quotes. Building this forced me to look at how Moodle, Open edX, Canvas LMS, and Chamilo handle the same problem.

The pattern is the same in all of them — and was the same in ours when we started.

Mistake #1: User-generated content treated like UI strings

Every LMS has solid gettext-style infrastructure for UI strings. "Sign in", "Course catalog", "Submit assignment" — these live in .po files (Moodle), Transifex (Open edX), i18n-js (Canvas), YAML (Rails-based). A translator translates the file once. Done.

User-generated content is a different problem entirely. When a teacher authors a course in Russian, the title — "Введение в Послание к Римлянам" — is a row in courses.title. An English-speaking student opens the catalog and sees Cyrillic. The UI is translated. The content isn't.

	UI strings	User-generated content
Examples	"Sign in", "Submit"	Course title, lesson body, quiz question
Source	Fixed catalog of values	Unbounded user input
Tool	gettext / Transifex / YAML	Runtime translation (Google, DeepL, Gemini)
When	Build / release time	Runtime (lazy or eager)
Storage	Locale file	Separate cache table
Common bug	None major	Treated like UI strings → only one language ever shown

Moodle's workaround is the multilang filter — you wrap content in …… and a filter shows the matching one. This is a 2008 solution. It puts the entire burden on the teacher: they must author every piece of content twice, in every language. Most don't, and the platform falls back to "show whatever the teacher wrote first."

The shape of the right answer is a separate translation cache:

CREATE TABLE content_translations (
  entity_type  TEXT NOT NULL,    -- 'course', 'lesson', 'quiz_question'
  entity_id    UUID NOT NULL,
  field        TEXT NOT NULL,    -- 'title', 'description', 'body'
  locale       TEXT NOT NULL,    -- 'ru', 'en', 'uk', 'es'
  content      TEXT NOT NULL,
  source       TEXT NOT NULL,    -- 'human' | 'machine' | 'canonical'
  cached_at    TIMESTAMPTZ NOT NULL,
  PRIMARY KEY (entity_type, entity_id, field, locale)
);

Teacher authors in one language. A translation worker fills in the others lazily (first request) or eagerly (on publish). The course-detail endpoint joins on (entity_type, entity_id, field, viewer_locale).

The architectural decision: content is not a UI string and cannot live in the same system. If your LMS uses gettext for "Submit assignment" and the same mechanism for course titles, that's the bug.

Mistake #2: No accommodation for length variance

English is dense. Russian runs ~25–30% longer for the same meaning. German is comparable. Finnish is worse. Arabic is shorter — and right-to-left, its own category.

Most LMS UIs are designed in English. Buttons that fit "Save" don't fit "Сохранить". Nav tabs that fit "Courses" wrap to two lines for "Курсы и обучение". Mobile breaks first.

Part of the fix is CSS:

/* Reserve space against the longer-language baseline */
.action-button {
  min-width: 8rem;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

/* Tabular content: don't let translation reflow the grid */
.lesson-list-cell {
  min-height: 4.5rem;  /* fits 2-line Russian titles without shift */
}

But the real fix is testing every screen in your longest-content language, not just English. Most teams hire designers who only see the English mock and don't realize their "Continue" button is broken in Russian until a user reports it.

What helped us: a Storybook locale switcher defaulting to Russian (not English), and a Playwright snapshot suite that screenshots both locales. The first commit that breaks Russian layout is caught in CI, not by a user.

Mistake #3: Canonical content forced through translation

This is the bug that motivated our entire content-translation rewrite.

A teacher in Russian writes: "Послание к Римлянам 8:28 говорит, что все содействует ко благу". The course gets auto-translated to English. Naively you send the whole string to Google Translate or DeepL, and you get back: "Romans 8:28 says that everything works together for good." That's almost a real Bible verse — but it isn't quoting any actual translation. It's a translation of a translation.

You don't want that. You want the actual KJV (or NIV, or ESV) text of Romans 8:28 spliced in.

Same problem exists everywhere there's canonical content:

Programming courses with code samples (don't translate the variables!)
Math curricula with formulas
Legal courses citing statutes
Medical courses citing clinical-trial registries
Literature courses with original-language quotes

Most LMSes don't separate "translatable prose" from "canonical artifact" — so when they auto-translate, the canonical content gets mangled or invented.

Our pattern: parse the source for canonical references, replace each with a placeholder token, translate the surrounding prose, then substitute the canonical text back from a separate lookup.

def translate_with_canonical_preservation(
    text: str, source_lang: str, target_lang: str
) -> str:
    # 1. Find canonical references in either language
    refs = extract_bible_refs(text, lang=source_lang)
    # [{"raw": "Послание к Римлянам 8:28", "book": "ROM", "chapter": 8, "verses": [28]}]

    # 2. Replace each with a unique placeholder
    placeholders = {}
    for i, ref in enumerate(refs):
        token = f"⟦CANON_{i}⟧"
        placeholders[token] = ref
        text = text.replace(ref["raw"], token, 1)

    # 3. Translate the token-bearing string
    translated = translate(text, source_lang, target_lang)

    # 4. Substitute the canonical text back, looked up in the target translation
    for token, ref in placeholders.items():
        canonical_text = lookup_canonical(ref, target_lang)  # KJV for en, Synodal for ru
        translated = translated.replace(token, canonical_text)

    return translated

How `extract_bible_refs` handles the cross-language book-name matrix

Detection is a regex over a normalized book-name dictionary. Each canonical book has an entry like:

BOOKS = {
    "ROM": {
        "en": ["Romans", "Rom", "Rom."],
        "ru": ["Послание к Римлянам", "Римлянам", "Рим", "Рим."],
        "uk": ["Послання до Римлян", "Римлян", "Рим"],
    },
    # ... 65 more books
}

The regex is built per request as (book_alias_1|book_alias_2|...)\s+(\d+):(\d+)(?:[-–](\d+))? so it accepts: Romans 8:28, Послание к Римлянам 8:28, Рим 8:28, Рим. 8:28, Romans 8:28-29, Romans 8:28a.

Sundry edge cases: chapter-only refs (Romans 8 — whole-chapter), letter suffixes (8:28a — first half of verse), em-dash vs hyphen, non-breaking spaces. Each lives in unit tests.

lookup_canonical pulls from a canonical text table keyed by (book, chapter, verse_start, verse_end, translation). Cache the final translated string keyed by (entity_id, field, locale) per Mistake #1.

This is ~400 lines we wouldn't have written if any of the LMSes we looked at had solved this for us.

What I want to hear back

These are the three patterns I keep seeing. They're not the only ones (cache invalidation on edits, RTL layout, Slavic plural forms — separate posts), but they're the ones every general-purpose LMS skips.

If you've shipped i18n in an LMS, education platform, or any content product:

Do you separate UI strings from content? What's your storage shape?
How do you handle length variance? Do you test the long-language layout in CI?
Do you have canonical content that mustn't be translated? Code samples, equations, citations? How are you handling it?

Curious where teams have landed. The patterns above are our current best, not our last word.

The project that drove all of this is open source:

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Changelog

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not enterprise pricing models.
Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.

Features

Area	What you get
Course authoring	Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio)
Assessments	Multiple-choice, true/false, short-answer, and essay

…

View on GitHub

I wrote 'these fields are translatable' in five different files. Then I stopped.

Vadym Arnaut — Sun, 10 May 2026 15:33:29 +0000

The same fact, written in five places

I'm building an LMS where teachers write courses in one language and students read them in another. So content i18n. Standard problem.

What surprised me was how many places "this field gets translated" had to live.

1. supabase/migrations/...sql        CHECK (entity_type IN (...))
2. backend/app/schemas/...py          Literal["course", "module", ...]
3. backend/app/models/...py           Mapped[Literal[...]]
4. backend/app/services/.../walker.py if entity_type == "course": ...
5. backend/app/api/v1/announcements   call reconcile_entity(...)

Each of these is its own commit, its own PR, its own author. They drift independently. You add a new translatable entity in March, you forget one of the five, and a Russian student reads English in their dashboard until somebody reports it.

I shipped that bug twice in two months before I got tired of it.

What the bug looks like in practice

Concretely: I added an Announcement table that has translatable title and body. Things I had to update:

The Postgres CHECK constraint to add 'announcement' to the allowed entity_type values. Forgot this one. All inserts started failing with IntegrityError. Took two days to notice because the route swallowed the exception and just logged.
The Pydantic EntityType = Literal[...] so the API contract types match.
The SQLAlchemy Mapped[Literal[...]] on the ContentTranslation row.
The tree walker that, when a course is published, decides what to translate. Had to add a new branch for announcements.
The per-entity hook on the announcement-create route. Every other write route already called reconcile_entity() after commit. This one didn't, so edits silently never propagated.

Five places. Each one is a single line or a single function call. None of them is hard. The problem is that the knowledge of "this entity is translatable" is duplicated. Every duplicate is a chance to drift.

One registry, five readers

Collapse the duplication into a declarative registry. Every layer reads from it. Adding a new entity is one entry plus one migration, end of story.

# backend/app/services/translation/registry.py

@dataclass(frozen=True, slots=True)
class FieldSpec:
    name: str                     # logical name in our API
    column: str                   # column in DB
    model_attr: str | None = None # ORM attr if it differs

@dataclass(frozen=True, slots=True)
class EntityRegistration:
    entity_type: str
    fields: tuple[FieldSpec, ...]
    resolve_course: Callable[[Session, Any], Course | None]
    build_context: Callable[[Any, Course], str]

_REGISTRATIONS: tuple[EntityRegistration, ...] = (
    EntityRegistration(
        entity_type="course",
        fields=(FieldSpec("title", "title"), FieldSpec("description", "description")),
        resolve_course=lambda _db, c: c,
        build_context=lambda _co, c: f"Course title for «{c.title}»",
    ),
    EntityRegistration(
        entity_type="announcement",
        fields=(FieldSpec("title", "title"), FieldSpec("body", "body")),
        resolve_course=_resolve_course_via_attr("course_id"),
        build_context=lambda ann, c: f"Announcement on course «{c.title}»",
    ),
    # ... seven more entries
)

def all_entity_types() -> frozenset[str]:
    return frozenset(r.entity_type for r in _REGISTRATIONS)

The same five layers now read from this:

Pydantic schema declares the Literal once, by hand, in the module that other layers import from:

# backend/app/schemas/protocol.py
EntityType = Literal[
    "course", "module", "chapter", "chapter_block",
    "quiz", "quiz_question", "quiz_option",
    "assignment", "announcement", "course_event", "cohort",
]

That's the only manual list. A static test asserts it stays in lockstep with the registry:

def test_pydantic_literal_matches_registry():
    declared = set(get_args(EntityType))
    assert declared == all_entity_types()

SQLAlchemy model imports the same EntityType.

Walker:

def collect_translatable_fields(course, db):
    for reg in _REGISTRATIONS:
        for entity in reg.entities_for_course(db, course):
            for field in reg.fields:
                yield (reg.entity_type, entity, field)

Per-entity hook:

def reconcile_entity_if_course_published(db, entity_type, entity):
    reg = next((r for r in _REGISTRATIONS if r.entity_type == entity_type), None)
    if reg is None:
        return
    course = reg.resolve_course(db, entity)
    if course and course.status == "published":
        run_translation(db, reg, entity, course)

Migration: still by hand, but it's the only place that doesn't auto-update. So we test it.

def test_postgres_check_constraint_matches_registry():
    declared = _declared_entity_types_from_migration()
    actual = all_entity_types()
    assert declared == actual, (
        "Migration CHECK constraint and registry are out of sync. "
        f"Missing in migration: {actual - declared}. "
        f"Stale in migration: {declared - actual}."
    )

Now adding a new translatable entity is one new EntityRegistration plus one migration that adds the value to the CHECK. Both visible side by side in the same PR. The other three layers fix themselves at import time.

The CI guard that makes drift impossible

Even with the registry, one vulnerability remains. A new write route that mutates a registered entity but never calls the reconcile hook. Routes are individual files. There's nothing structural to stop the omission.

The fix is a static test that introspects every FastAPI route at import time:

TRANSLATION_HOOK_NAMES = (
    "reconcile_entity",
    "reconcile_entity_if_course_published",
    "run_course_translation_pipeline_if_published",
)

def test_writes_on_translatable_entity_call_a_hook():
    """Every POST/PUT/PATCH whose path or body schema mentions a
    translatable entity must reference one of the canonical reconcile
    hooks somewhere in its source file."""

    failures: list[str] = []
    for route in app.routes:
        if not isinstance(route, APIRoute):
            continue
        if not (route.methods & {"POST", "PUT", "PATCH"}):
            continue
        if not _route_touches_translatable_entity(route):
            continue
        source = inspect.getsource(inspect.getmodule(route.endpoint))
        if not any(hook in source for hook in TRANSLATION_HOOK_NAMES):
            failures.append(f"{route.methods} {route.path} ({route.endpoint.__name__})")

    assert not failures, (
        "These write endpoints touch a translatable entity but never call "
        "a reconcile hook:\n  " + "\n  ".join(failures)
    )

Inverse rule for read endpoints:

def test_reads_returning_translatable_schemas_accept_language():
    """Every GET that returns a translatable response schema must
    declare an Accept-Language parameter so the locale overlay applies."""

Both are plain pytest. No real database, no live HTTP, no test client. They use FastAPI's app.routes plus inspect.getsource. They fail the build in under one second.

The first time I ran them they immediately surfaced two real holes: the announcement-create route and the course-event-create route. Both had been merged for weeks. No user had hit them yet because both routes were teacher-only and had low traffic, but they would have failed the moment a teacher published an announcement on an EN-locale course with RU students enrolled.

I added a KNOWN_VIOLATIONS set to the test (cite the follow-up PR or issue, no silent skipping), fixed both routes the same hour, and emptied the set. The set has stayed empty since.

What the pattern actually buys

Adding a translatable entity is now a five-line PR. One registry entry, one migration line. CI catches anything you forgot.

Failures are loud, not silent. The CI guard names the offending route. There is no "huh, why doesn't translation work for this endpoint" debugging session anymore.

The registry doubles as documentation. Want to know what gets translated? Read one file. There is no git grep archaeology.

The pattern generalizes. Anywhere a single fact about your domain has to be repeated across multiple layers, the same shape applies. Audit logging. RLS. Soft delete. Encryption. Each one is a registry plus a static test that introspects routes or models and demands they reference the canonical hook.

That last bit is what made me write this post. The translation pipeline was the prompt, but the pattern is not about translation. It is about rejecting the idea that drift between layers is something you live with. You don't have to. Static introspection of your own code is dirt cheap and almost nobody does it.

Where it lives

The full implementation is in a small open-source LMS at github.com/ArVaViT/equip. Registry is backend/app/services/translation/registry.py. CI guard is backend/tests/test_translation_coverage.py. MIT-licensed, contributors welcome if any of this resonates.

Thanks for reading.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Changelog

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not enterprise pricing models.
Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.

Features

Area	What you get
Course authoring	Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio)
Assessments	Multiple-choice, true/false, short-answer, and essay

…

View on GitHub

Don't trust the LLM with scripture: a canonical-text substitution layer for Bible quotes

Vadym Arnaut — Sun, 10 May 2026 15:12:31 +0000

The problem

I'm building equip, an open-source LMS for Bible schools. The product is bilingual (Russian and English) and most teacher-authored content goes through a Gemini-backed translation pipeline.

For 95% of the content this is fine. Course titles, chapter prose, quiz questions, announcements, the LLM does an honest job and the worst that happens is a slightly clumsy turn of phrase.

For Bible quotes it isn't fine. At all.

A teacher writes a Russian course quoting Acts 1:8 from the Synodal translation, the canonical Russian-language text since 1876. An English-locale student reads it. The expected behaviour is that they see Acts 1:8 in the King James Version, the canonical English-language text since 1769. Not Gemini's interpretation of the Synodal text.

This isn't a stylistic preference. KJV and Synodal are the texts these communities cite, memorize, and study from. A model paraphrase, even a "good" one, breaks the contract: students need to read the same wording their pastor will quote on Sunday. And every LLM, including the strongest ones, paraphrases scripture. Sometimes subtly, sometimes egregiously.

The naive fix is a prompt rule: "Bible verses must be preserved verbatim." It does not work. The model still paraphrases, especially across languages where there is no direct passthrough. So we built something else.

The constraint

Every quote we care about is one of two public-domain corpora:

King James Version (1769) for English. ~31,103 verses, ~4.5 MB as flat JSON.
Synodal (1876) for Russian. ~30,111 verses, ~6.1 MB as flat JSON.

Both bundle into the backend. They never change. They are the source of truth for any rendered Bible quote in either locale.

The only problem is figuring out, for any given chunk of teacher-authored HTML, which substrings are quotes that need this canonical-text treatment, and what verse exactly each one is.

The architecture

The pipeline runs in three steps around each Gemini call:

HTML in source locale
        |
        v
  pre_substitute(html, source_locale)
   - find <blockquote> + reference pairs
   - confirm canonical via similarity match
   - swap verse text for VERSE_<hex> marker
        |
        v
   markered HTML  ----->  Gemini translate  ----->  translated HTML
                                                            |
                                                            v
                                              post_substitute(html, subs, target_locale)
                                               - replace each marker with
                                                 the canonical target-locale verse
                                               - localize the (Acts 1:8) reference too
                                                            |
                                                            v
                                                  HTML in target locale

1. Detect

We walk every <blockquote> in the HTML. Two layouts in real-world content:

<!-- A: reference inside the blockquote (most Synodal-style citations) -->
<blockquote>...verse text... (Деян. 20:28).</blockquote>

<!-- B: reference outside, immediately after </blockquote> -->
<blockquote>...verse text...</blockquote> (Acts 1:8).

We try the inside layout first, fall back to a 120-character lookahead window after the closing tag. The reference parser is a regex built from a 66-book canonical alias list (Matthew / Matt. / Mt. / Матфей / Мф. / Матф. / etc.) so a sloppy book pattern doesn't accidentally swallow surrounding prose like "See Acts" as a book name.

2. Confirm

Detection alone isn't enough. The author might have paraphrased the verse themselves, or written commentary, or quoted only part of the verse. We don't want to "correct" intentional paraphrases.

So for every detected blockquote+reference pair, we look up the canonical text in the source locale (Synodal for ru, KJV for en) and compare it to the author's text using difflib.SequenceMatcher. If similarity is at least 0.80, this is a real canonical quote and gets the substitution treatment. Below 0.80, we leave it alone and the LLM handles it under the existing "leave verses untouched" prompt rule (a fallback, not the main mechanism).

We tested the threshold empirically on real course content. Author copy-pastes of Synodal hit 0.95 and above. Paraphrases land below 0.6. The 0.80 threshold tolerates minor punctuation differences (em-dashes, smart quotes, ё vs е normalization) without false-matching a paraphrase.

3. Substitute

When we accept a quote, we replace the verse text with a marker:

VERSE_a1b2c3d4e5f6g7h8

Constraints this marker satisfies:

Plain ASCII. An earlier version used Unicode Private-Use Area characters as fences. They were invisible in the editor and silently broke ASCII assertions in tests.
Postgres-TEXT-safe. The first prototype used NUL-byte fences (\x00...\x00). Postgres TEXT rejects NUL. The translated marker came back stripped, leaving raw VERSE_<hex> substrings visible to students. Took an embarrassing prod inspection to catch.
Identifier-shaped. This matters because Gemini's "preserve placeholders verbatim" prompt rule applies to identifier-shaped tokens. VERSE_a1b2c3d4e5f6g7h8 reads as a placeholder. ≪V≫ does not.
Random hex suffix. Multiple verses in one document each get a unique marker so substitutions round-trip independently.

We also extend the marker leftwards through the opening parenthesis of the reference if there is one, so we don't leave a stray ( inside the marker-replaced verse text. The reference notation itself, (Деян. 20:28)., is preserved as-is in the markered HTML and survives translation untouched (parens-with-digits looks like data to the model).

4. Restore

After Gemini returns the translated HTML, post_substitute walks the substitution list and:

Replaces each marker with the canonical target-locale verse (canonical_target = lookup(ref, target_locale)).
Falls back to the original source-locale text when the target lookup misses (e.g. a verse the bundled JSON happens to lack), better than leaving a marker visible.
Rewrites the surviving reference notation to the target locale's conventional short form. (Acts 1:8) becomes (Деян. 1:8). (Матф. 28:19) becomes (Matt. 28:19). The book-name display table is keyed by the same canonical slug as the alias parser, so adding a new book is one row in two places.

What it looks like in production

Russian-locale teacher writes:

<p>Завершающее повеление Иисуса ученикам:</p>
<blockquote>«Итак идите, научите все народы, крестя их во имя
Отца и Сына и Святаго Духа» (Матф. 28:19).</blockquote>

English-locale student reads:

<p>The final command of Jesus to His disciples:</p>
<blockquote>Go ye therefore, and teach all nations, baptizing them in the
name of the Father, and of the Son, and of the Holy Ghost: (Matt. 28:19).</blockquote>

Note three things:

The blockquote's verse text is the canonical KJV verbatim, not Gemini's interpretation of the Synodal.
The reference is (Matt. 28:19), not (Матф. 28:19). Gemini didn't translate the book name. Our display table did.
The surrounding prose ("The final command of Jesus to His disciples:") is the LLM doing its job on the parts the LLM should be doing.

Edge cases that bit us

Synodal short forms missing from the alias map. First version had матфей/мф/от матфея for Matthew but missed Матф., the most common abbreviation in actual Synodal-printed Bibles. Russian-authored content silently failed substitution and the verse leaked through Gemini paraphrased. Caught in production via Datadog RUM. Fixed by expanding aliases for every Gospel and Pauline epistle (мар, лук, иоан, фил, 1 фесс, 1 иоан, etc.) plus a contract test that asserts every canonical slug has an alias entry.
Reference outside the blockquote. Some content puts the citation after </blockquote> instead of inside it. The first version captured the verse correctly but didn't track the outside reference, so a Russian student saw a Synodal verse next to a stray English (Acts 1:8). Fixed by storing the outside ref text on the substitution record and running the same locale rewrite on it during post.
Marker spacing. The marker swallowed the trailing whitespace and closing curly quote of the blockquote, so the post-substituted output read …canonical text.(Matt. 28:19). with no space. Re-introduced a single ASCII space when the tail starts with (.
Verse range references. (Acts 1:8-10) localizes correctly to (Деян. 1:8-10) because the display formatter respects the verse_end field on the ref struct. The corresponding canonical lookup joins the verses with a single space and falls back to None if any verse in the range is missing.

What's interesting about this approach

The Bible substitution layer doesn't compete with the LLM. It uses the LLM for what it's good at (translating prose, preserving HTML structure, transliterating proper nouns) and replaces the LLM where the LLM is wrong (touching canonical text). Each layer has a clean job.

The same pattern applies anywhere you have:

A small, public-domain or licensed corpus of canonical text
A larger surface that needs LLM translation
A reliable way to detect quotes from the corpus inside the surface

Examples I can think of: legal contracts citing statute, scientific writing citing equations or named constants, classical literature quoting older works in their established translations. The shape is the same. Detect the canonical chunk, swap it for a placeholder, let the LLM handle the surrounding prose, restore the canonical chunk in the target locale.

Code

All of this lives in backend/app/services/bible/:

books.py: 66-book canon, alias map, per-locale display names
references.py: regex parser built from the alias list
store.py: bundled JSON loader (KJV / Synodal)
substitution.py: pre/post substitute, similarity threshold, marker tokens
data/: kjv-en.json (4.5 MB) + synodal-ru.json (6.1 MB), both public-domain

39 unit tests cover the alias map, the reference parser, the locale store, full round-trips for both directions, the verse-range case, and the spacing regression. The pipeline integrates into the broader translation registry which also handles non-Bible content.

Repo: github.com/ArVaViT/equip (MIT)

How you can help

The pipeline above is one corner of a small open-source LMS for Bible schools and volunteer-run training programs. If you've worked on translation pipelines, LLM I/O hardening, or just like the idea of an LMS that respects scripture as a source of truth, the issues tab is open. Star the repo if you want to follow along.

Thanks for reading.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Changelog

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not enterprise pricing models.
Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.

Features

Area	What you get
Course authoring	Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio)
Assessments	Multiple-choice, true/false, short-answer, and essay

…

View on GitHub

Two weeks of building Equip in public: first contributor, bilingual content, real production bug

Vadym Arnaut — Sun, 10 May 2026 02:13:11 +0000

Two weeks ago I posted "Open Source Equip, we need your help" and asked for contributors.

Today the first community PR landed. Plus a stack of changes shipped that I think are worth sharing, both because some of them are genuinely interesting, and because it gives a concrete picture of where help would land.

Repo: github.com/ArVaViT/equip (MIT, looking for stars and PRs)
Live: equipbible.com

The first community PR

Kushal picked up a good first issue (a floating scroll-to-top button), opened a PR, took a code review without taking it personally, pushed clean follow-up commits, and got merged the same day. That sounds small. For a tiny open-source repo it is the most important kind of small.

If you are reading this and have never opened a PR on someone else's project, this is exactly the type of issue we keep around for that reason. There are more on the board.

What shipped: bilingual content (RU and EN)

The biggest piece of work in these two weeks was the translation pipeline. Goal: a teacher writes a course in their own language, students read it in theirs, no UI dropdown, no "main language", no humans needed in the loop.

How it works:

Every teacher-authored field (course title, module, chapter, rich-text block, quiz, assignment, announcement, calendar event, cohort) is registered once in backend/app/services/translation/registry.py. The registry is the single source of truth for what gets translated and how. Adding a new translatable entity is one entry plus a Postgres CHECK constraint update.
On publish (and on per-entity edits to a published course) a hook walks the registry, hashes the source text, and calls Gemini for any field whose hash changed. Result is cached in public.content_translations keyed by (entity_type, entity_id, field, locale).
The student's Accept-Language header drives an overlay layer at read time. The catalog, the chapter view, the certificate, all of it returns the locale the user asked for, falling back to the source.
A static CI guard introspects every FastAPI route. If a GET that returns a translatable schema is missing Accept-Language, or a POST/PUT/PATCH on a translatable entity does not reference one of the canonical translation hooks, the build fails. That sounds aggressive but it caught two real regressions during development.

The interesting part: Bible quotes do not go through the LLM

Letting an LLM "translate" scripture is a bad idea. Even the best models paraphrase. KJV and Synodal are public-domain canonical texts and students need to read the canonical wording, not a model's interpretation.

So the pipeline pre-substitutes around the LLM:

The translator detects <blockquote> plus a parenthesised reference like (Acts 1:8) or (Деян. 20:28), in the inside-the-quote layout and the outside-the-quote layout.
It compares the author's quoted text to the bundled canonical source-locale verse using SequenceMatcher. If similarity is at least 0.80, it is a real canonical quote and gets replaced with an ASCII marker like VERSE_a1b2c3d4e5f6g7h8 before the request goes to Gemini.
After translation, the marker is replaced with the canonical target-locale verse from a 4.5 MB KJV (1769) JSON or a 6.1 MB Synodal (1876) JSON, both bundled.
The reference itself, (Acts 1:8), is also rewritten in the target locale's conventional short form, (Деян. 1:8).

Below the 0.80 similarity threshold the substitution skips and the LLM handles the quote with a "leave verses untouched" prompt rule as a fallback.

There are 66 books in the canonical Protestant canon, each with a list of recognised aliases (including Synodal abbreviations like Матф. and Деян. that the first version of the parser quietly missed). All 66 are in regression tests.

What observability caught the day we plugged it in

Datadog RUM had been wired into the frontend for a while but I was not actively looking at it. The day I finally hooked up the API, the read endpoint immediately surfaced something useful: 10 errors across 4 sessions in 24 hours, all the same:

TypeError: Failed to fetch dynamically imported module:
    .../assets/ChapterView-DYS-mrkM.js

This is the classic Vite SPA stale-chunk failure. After a deploy, every open tab is still holding the old index.html whose <script> tag references chunk hashes the new build no longer publishes. The next lazy-route navigation throws this error. The previous behaviour was to show a generic "Something went wrong" page with a manual "Refresh" button. Most users would close the tab and never come back.

Fix is a few lines in the ErrorBoundary: detect the chunk-load signature (Vite's, webpack's, and the named ChunkLoadError all have different messages), do a single window.location.reload(), guard against loops with a 60 second cooldown in sessionStorage. Reloading fetches the fresh index.html and the user is back where they were.

The point is not the bug. The point is that I would not have known about this without the telemetry. CI was green. Everything looked healthy. Real users were silently churning.

What else moved (compressed list)

Auth callback page is fully translated now. Russian users no longer see English during email confirmation or password reset.
Course detail page is fully translated, including the admin "manage course" flow that previously hid the enroll button.
OpenGraph and Twitter cards added so links to courses unfurl properly when pasted into Slack, Telegram, X, LinkedIn.
Backend favicon is now a real dark-variant of the brand glyph instead of an empty 204.
Internal cleanups: 30+ hardcoded English strings routed through i18n, repo stripped of editor-specific tooling references so it reads neutral about how a contributor authors code, security advisor warnings cleared.

Where contributors fit in

Same answer as two weeks ago, with sharper edges:

If you like...	Look at...
React + TypeScript + Tailwind	the issues tagged `frontend` and `good first issue`
Python + FastAPI + Pydantic	the issues tagged `backend`
Accessibility	`prefers-reduced-motion` is missing in a few animated bits, focus management in modals could be tighter
i18n	adding a third locale would mean one new entry in the registry, one new `_translation` JSON, one new bundled Bible (or none if the language can fall back to a sibling). The pipeline is built to scale here.
Docs	"I tried to set this up on macOS / Linux and these were the snags" stories help more than you would think
Testing	Playwright E2E for the student happy path is on the roadmap and unstarted

The bar to contribute is not "do not break anything". The bar is "open a draft PR with a question, talk it through, push some commits, get reviewed". Kushal did exactly that in a few hours.

One line again

Free LMS, small scale, real classrooms, with a translation pipeline that does not paraphrase scripture. Star the repo, pick an issue, ping me anywhere.

github.com/ArVaViT/equip

Thanks for reading. See you in the issues tab.

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Changelog

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not enterprise pricing models.
Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.

Features

Area	What you get
Course authoring	Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio)
Assessments	Multiple-choice, true/false, short-answer, and essay

…

View on GitHub

Equip — open-source Bible LMS, we need your help (React, FastAPI, Supabase)

Vadym Arnaut — Sat, 25 Apr 2026 05:01:11 +0000

Why I’m writing this

Small Bible schools, home groups, and volunteer-run training programs still run classes on paper, messengers, and spreadsheets. Big LMS products are either too expensive or too heavy for a team that has no DevOps and no budget.

Equip is a free, open-source learning platform built for that reality: tens to low hundreds of users, not “enterprise 10k seats”.

We’re on GitHub (MIT) and we’d love contributors — code, UI, docs, accessibility, and ideas.

What it does today

Courses → modules → chapters with a TipTap rich editor (text, images, YouTube, callouts, audio).
Quizzes — multiple choice, true/false, short answer, essay; teacher grading and extra attempts when needed.
Assignments + gradebook, progress, certificates (with approval flow).
Teacher & admin tools: cohorts, calendar, announcements, analytics, soft-delete / restore, CSV export.
Auth via Supabase (email/password + Google).
Deploy: Vercel (static frontend + serverless FastAPI backend), Postgres on Supabase with RLS.

Live app: equipbible.com

Roadmap: in the repo → ROADMAP.md

How to contribute: CONTRIBUTING.md

Stack (if you like concrete tech)

Layer	Tech
UI	React 18, TypeScript, Vite, Tailwind, shadcn/ui, TipTap, Radix
API	Python 3.12, FastAPI, SQLAlchemy 2, Pydantic 2
Data	PostgreSQL (Supabase), migrations in `supabase/migrations/*.sql`
CI	GitHub Actions — lint, typecheck, tests (backend + frontend)

We keep conventional commits, no Docker in the project by design, and we care about types (mypy + strict TypeScript) and a clean codebase.

How you can help (no need to be a “10×” developer)

Good first issues — filter by good first issue on GitHub.
UI/UX — especially accessibility and a calmer, “editorial” reading experience.
Docs — setup stories from real machines (Windows / macOS / Linux) help a lot.
i18n — the product UI is largely Russian today; if you care about internationalization, that’s a meaningful roadmap area.

Open a draft PR, ask in an issue, or fork and experiment — we’re building in public and want this to stay approachable for nonprofits and volunteers.

One line pitch

Free LMS, small scale, real classrooms — if that resonates, star the repo and pick an issue.

Thanks for reading — hope to see you in the issues tab 🤝

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

A free, open-source learning management system built for Bible schools church ministries, and nonprofit educational programs

Live demo · Roadmap · Contributing · Changelog

Why this project?

Equip is designed to change that:

Free forever — MIT-licensed, no paywalls, no "premium" tiers.
Simple to deploy — one-click Vercel deploy with a free Supabase database. No Docker, no servers to manage.
Built for small scale — optimized for 20-100 students, not enterprise pricing models.
Contributor-friendly — clear docs, conventional commits, issue templates, and a welcoming community.

Features

Area	What you get
Course authoring	Courses, modules, chapters, rich content blocks (TipTap editor with images, YouTube, callouts, audio)
Assessments	Multiple-choice, true/false, short-answer, and essay

…

View on GitHub

DEV Community: Vadym Arnaut

4 footguns integrating YouVersion's new platform API — and a clean Verse of the Day

Footgun #1: /v1/bibles returns 422 without language_ranges[]

Footgun #2: all_available=true reveals the real catalog

Footgun #3: content is HTML, even when you didn't ask

Footgun #4: their VOTD endpoint exists, but you cannot pick the verses

The shape that worked: deterministic by day, cached by day

A few things to weigh before you adopt this

What I'd ask the room

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Why this project?

Features

Two days lost to PGRST116: when Supabase RLS hides a successful write

The setting

The bug

Why this was hard

The fix

What I'd tell past-us

What I want to hear back

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Why this project?

Features

The 3 i18n mistakes every open-source LMS makes

Mistake #1: User-generated content treated like UI strings

Mistake #2: No accommodation for length variance

Mistake #3: Canonical content forced through translation

How extract_bible_refs handles the cross-language book-name matrix

What I want to hear back

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Why this project?

Features

I wrote 'these fields are translatable' in five different files. Then I stopped.

The same fact, written in five places

What the bug looks like in practice

One registry, five readers

The CI guard that makes drift impossible

What the pattern actually buys

Where it lives

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Why this project?

Features

Don't trust the LLM with scripture: a canonical-text substitution layer for Bible quotes

The problem

The constraint

The architecture

1. Detect

2. Confirm

3. Substitute

4. Restore

What it looks like in production

Edge cases that bit us

What's interesting about this approach

Code

How you can help

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Why this project?

Features

Two weeks of building Equip in public: first contributor, bilingual content, real production bug

Two weeks ago I posted "Open Source Equip, we need your help" and asked for contributors.

The first community PR

What shipped: bilingual content (RU and EN)

The interesting part: Bible quotes do not go through the LLM

What observability caught the day we plugged it in

What else moved (compressed list)

Where contributors fit in

One line again

ArVaViT / equip

Free, open-source LMS for Bible schools, ministries, and nonprofit educational programs. React + FastAPI + Supabase.

Equip

Why this project?

Footgun #1: `/v1/bibles` returns 422 without `language_ranges[]`

Footgun #2: `all_available=true` reveals the real catalog

Footgun #3: `content` is HTML, even when you didn't ask

How `extract_bible_refs` handles the cross-language book-name matrix