DEV Community: Vadym Arnaut

There is no source language: a manifesto for symmetric multilingual content

Vadym Arnaut — Thu, 28 May 2026 14:50:42 +0000

Three weeks ago I shipped a bilingual LMS. The architecture modeled one language as source and the rest as overlay: a source_locale column on every translatable entity, an MT pipeline reading source rows and writing overlay rows. It worked. Students used it. Certificates issued. Three published courses, fourteen real users, end-to-end.

Last week it broke in a way that did not fit a bug fix.

A teacher whose interface was set to English wrote a course entirely in Russian. The system saw teacher.preferred_locale = 'en', stamped source_locale = 'en' on every course field, and then served Russian students a course labelled "Russian translation of an English source" — when no English source existed, ever. The fallback path showed [translation missing] placeholders on a course that was, in fact, perfectly written in the language being requested.

The first fix attempt was a heuristic: detect the actual character set of the content and derive source_locale from that, not from the teacher's UI. Better. Still wrong, because per-entity source locale assumes the entity is monolingual — and there is no rule that says it has to be. A course with an English title and a Russian description is one entity with no single answer to "which locale is source?"

The second attempt moved detection per-field. Better still. Still wrong, because per-field source locale assumes the field is monolingual — and there is no rule that says it has to be. A bilingual paragraph (a sentence in English, a Russian phrase set off in italics, a quoted scripture reference) has no single answer either.

At that point the model is the bug, not the heuristic.

Locale is just a column

The new schema, shipped to main last night across eight stacked PRs:

CREATE TABLE content_versions (
    id                 uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    entity_type        text NOT NULL CHECK (entity_type IN (
                           'course','chapter_block','assignment','cohort',
                           'course_event','announcement', ...
                       )),
    entity_id          uuid NOT NULL,
    field              text NOT NULL,
    locale             text NOT NULL CHECK (locale IN ('en','ru')),
    body               text NOT NULL,
    origin             text NOT NULL CHECK (origin IN ('human','mt')),
    source_version_id  uuid REFERENCES content_versions(id),
    superseded_by      uuid REFERENCES content_versions(id),
    created_at         timestamptz NOT NULL DEFAULT now(),
    created_by         uuid REFERENCES auth.users(id)
);

CREATE UNIQUE INDEX content_versions_active_unique
ON content_versions (entity_type, entity_id, field, locale)
WHERE superseded_by IS NULL;

Every (entity, field, locale) is its own row. There is no source locale and no overlay. There are rows that exist because a human wrote them, rows that exist because the MT pipeline produced them, and the lineage between them. The thing that says "this Russian title was machine-translated from that English title" is source_version_id. The thing that says "an editor revised it" is superseded_by. The thing that says "what language is this row" is locale. No row outranks another by default.

The model is symmetric. The data is the data. Adding a third language is INSERT INTO content_versions ... plus appending a string to a Pydantic Literal. Zero DDL. No schema deltas. No "let's refactor source_locale to be nullable for the Spanish migration."

What this fixes that you can name

The "Тайтл" bug class disappears entirely. There is no source_locale column to be wrong, so it cannot be wrong. A teacher's UI preference no longer leaks into the content model.

Mixed-language entities are first-class. A course with an English title and a Russian description is two content_versions rows. Each one is correct in isolation. No "what's the source locale of this course" question to argue about, because no field on the entity claims to know.

Translation history is preserved by construction. Editing a row creates a new row with superseded_by pointing at the old one. The previous translation is not overwritten or archived in some side table; it is still in content_versions, just with a non-null superseded_by. The active row is the one with superseded_by IS NULL, enforced by the partial unique index above.

Cascade invalidation gets precise. When the English title is edited, the MT rows that were generated from it — and only those — get invalidated, via source_version_id. The old code had to purge_course_translations(course_id) and re-translate everything, because the lineage was not recorded anywhere readable. The new code knows exactly which rows depend on which.

What stays true from before

The registry pattern still holds. The fact that an entity has translatable fields is declared once, in backend/app/services/translation/registry.py, and read by the orchestrator, the schemas, and the CI guard. The schema change did not move this; it sharpened it. The registry now declares "this entity has these fields in content_versions" instead of "this entity has these _ru/_en overlay columns."

The Bible substitution layer still holds. Canonical text — KJV, Synodal, anything where the wording is a contract with the reader — never goes through the LLM. The MT pipeline substitutes placeholders, translates the prose around them, restores canonical target-locale text. The new model did not touch this. It could not; canonical text is not translated content. It is content that happens to exist in multiple locales because the canon exists in multiple locales. The substitution layer just makes sure the canonical version is the one that ships.

The three-layer split still holds. UI strings, user-generated content, canonical artifacts — three problems, three mechanisms, one product. The new model only touches the middle layer. The other two were already right.

The principle, generalized

The "source language" idea is a residue of monolingual-first design. Pick almost any i18n library, almost any LMS, almost any CMS, and you will find the same implicit assumption: one language is canonical, the rest are derived. Defaults, fallbacks, base locales, primary languages, source-of-truth columns. They all encode the same idea — somebody's language is real, everybody else's is a copy.

For documentation, that may be honest. The MDN reference is in English; the French version is a translation of the English version; calling English the source is correct because it is. For a product that serves bilingual or multilingual users as equally first-class — a faith community, an immigrant network, a multilingual school — the assumption is wrong, and it leaks. Every dropdown that says "EN (Original)", every fallback_locale: 'en' in a config file, every test that asserts the English string and ignores the Russian one, is a cultural primacy choice masquerading as engineering simplicity.

The cost of refusing the assumption is real but bounded. The backfill script is ~550 lines of dual-write reconciliation. The schema is symmetric, so there is no per-language DDL. Read paths read one table, not "canonical column union overlay table." The whole migration is in flight as a six-phase stacked PR — half shipped, the rest sequenced with DO NOT auto-merge until previous live + 7 days, take pg_dump, confirm PITR window, schedule Tue/Wed UTC. Boring, careful, recoverable. The principle is sharp; the rollout is not.

How to verify you have the same bug

Two checks. If your data model has a source_locale (or original_locale, or default_locale) column on a translatable entity, you have a primary language. If your application config has a fallback_locale and your read paths use it when a translation is missing, you have a primary language. Either is the residue. Both is the full version.

The honest move is to model what is actually true: a course has content. Some of that content is in English. Some is in Russian. Some was written by a human. Some was generated by an MT pipeline from a specific human-written version. None of those facts make any language more real than any other.

Bigger than i18n

The deeper read is that the "source plus overlay" pattern is a default reach for any time you have versions of the same thing in different shapes: translations, variants, A/B copy, accessibility re-writes, plain-language summaries, audio scripts. The same model — every variant is a row, lineage is explicit, supersession is preserved, no variant is privileged by schema — generalizes cleanly past locale.

If you are building anything where multiple variants of the same content need to coexist as equals, the question is not which one is the source. The question is what is the lineage, and who or what wrote each row.

If your bilingual app has a fallback locale, you have already chosen which language is real.

Equip is open source under MIT at github.com/ArVaViT/equip. Live at equipbible.com. The content_versions foundation migration is supabase/migrations/20260527230000_content_versions_foundation.sql. The six-phase rollout spans PRs #531 through #553 — Phase 1 (dual-write) is fully merged across all eleven translatable entity types; Phases 2 through 5 (dual-read with comparator, backfill, cv-primary read behind a flag, delete legacy + drop content_translations + drop the source text columns) are sequenced as an open stack.

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 · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

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…

View on GitHub

The auth_rls_initplan linter has a blind spot: SECURITY DEFINER bodies

Vadym Arnaut — Wed, 27 May 2026 21:46:29 +0000

If you've ever migrated a Supabase project to the wrapped (SELECT auth.uid()) pattern, you know the linter that flags the bare call. auth_rls_initplan reads every RLS policy expression and warns whenever auth.uid() is used directly instead of inside a scalar subselect. The wrap turns the call from a per-row evaluation into a single InitPlan. On a million-row table that is the difference between a 30ms read and a 30-second read.

The linter is good. It is also incomplete.

What it doesn't see

The linter introspects the policy expression itself. It does not walk into the body of any function the policy calls. So this passes the linter cleanly:

CREATE OR REPLACE FUNCTION public.is_owner(target_user uuid)
    RETURNS boolean
    LANGUAGE sql
    SECURITY DEFINER
    STABLE
AS $$
    SELECT auth.uid() = target_user;
$$;

CREATE POLICY rows_owner ON public.things
    FOR SELECT
    USING ((SELECT public.is_owner(user_id)));

Green linter. Slow query. The (SELECT ...) at the policy level caches the return value of is_owner(user_id), which itself depends on the row's user_id and runs every row. The auth call inside the function is back to per-row evaluation, and the InitPlan optimization the wrap was supposed to enable never kicks in.

The fix is the same wrap, one level deeper

Move the scalar subselect inside the function body:

CREATE OR REPLACE FUNCTION public.is_owner(target_user uuid)
    RETURNS boolean
    LANGUAGE sql
    SECURITY DEFINER
    STABLE
AS $$
    SELECT (SELECT auth.uid()) = target_user;
$$;

The function still runs per row, but the auth lookup inside it is the single InitPlan call the optimization was designed for.

How to find them

Grep the schema for auth.uid() inside function bodies, not just policies:

pg_dump --schema-only your_db \
    | rg -B 5 'auth\.(uid|jwt)\(\)' \
    | rg -A 2 'SECURITY DEFINER'

Or EXPLAIN ANALYZE the slow query and look for a subplan that fires once per row instead of once per query. If it scales with rows scanned, you have one of these.

The linter is a good first pass. This is the second pass to run before you call your migration done.

Equip: an open-source LMS for Bible schools — bilingual, scripture-aware, 4 weeks of real users

Vadym Arnaut — Thu, 21 May 2026 00:30:31 +0000

TL;DR. Equip is a free, open-source LMS built for Bible schools and small ministries. MIT-licensed. Bilingual Russian↔English out of the box — the same course renders in either language depending on who's reading. Self-hostable end-to-end on free tiers. 4 weeks in production: 14 real users, 3 published courses, 3 issued certificates. This post is what's in it, what's wired in, and how it's built.

Why this exists

Small Bible schools, home-church training programs, and missionary-prep tracks around the world run their coursework on paper, WhatsApp groups, or shared Google Sheets. The commercial LMSes either price out small ministries (Canvas, Blackboard), require an IT department to run (Moodle, Open edX), or fight the use case at every step. Most are built for K–12 or universities, not 30 students reading through Romans together.

I wanted an LMS that:

Costs zero to run for a 20–100 student school
Has no vendor lock-in (your data, your hosting)
Handles scripture correctly — more on this below, it turned out to be the most interesting constraint
Works in Russian and English without manual per-string translation
Is small enough that one nontechnical ministry admin can run it end-to-end

That's Equip. Live at equipbible.com.

Bilingual content, end-to-end

This is the feature that does the most work, so it goes first.

Russian and English UI ship together, but the more interesting decision is content. A teacher writes a course in their own language. When a student of the other language enrolls, every text field on every entity (course name, module title, chapter content, quiz question, quiz option, quiz explanation, assignment prompt) is auto-translated via Gemini Flash Lite and cached per (entity_type, entity_id, field, locale). The translation runs once per field and reads from cache thereafter. Cost per course is measured in cents.

The author always sees their own source-language content. The student always sees their target-language content. No "switch language to see English" toggle. No leaking source-locale strings. No [translation missing] placeholders.

Same /register page, two locales, rendered live by Equip:

The Cyrillic side isn't a different file or a different route. It's the same React tree with useTranslation(), plus the scripture passage in the left rail swapped from KJV (1769) to Synodal (1876) by a server-side substitution layer — see next section.

The scripture-preservation constraint

Most translation APIs (Gemini, GPT-4, DeepL) will happily paraphrase a Bible verse if you feed it into them as part of a longer paragraph. For a course where the exact wording of John 3:16 matters, that's a non-starter. "For God so loved the world" and "Because God loved the world this much" are not interchangeable in a Bible-study context, no matter how close the meaning.

Equip solves this outside the LLM:

Pre-process incoming HTML, detect <blockquote> + scripture-reference pairs.
Swap the verse text for an opaque ASCII placeholder (VERSE_<hex>).
Send the prose-with-placeholders to Gemini Flash Lite with a system prompt that lists "preserve placeholders verbatim" as a hard rule.
After the model returns, restore each placeholder with the canonical text from bundled translations: KJV 1769 for English, Synodal 1876 for Russian.

The model never sees the verse text. The translation never paraphrases scripture. Implementation lives in app/services/bible/substitution.py and is about 200 lines.

There's a fallback in the system prompt for paraphrased quotes that the substitution layer can't confidently match (similarity < 0.80 to canonical) — "leave the original verse text untouched." That covers content where the substitution layer can't reliably do its job.

What's wired in

Equip is small in scope but talks to a few external services where it makes sense to. Each one is a deliberate choice, not a default:

Service	What it does in Equip
YouVersion Platform API	Verse-of-the-Day card on the home dashboard. Reads the YV verse-of-the-day endpoint, caches the result per (locale, date). YV registration is on the non-commercial track, which is what shipped with our values from day one.
Gemini Flash Lite (Google AI)	Bilingual content translation pipeline (above). Flash Lite is overkill on quality and underkill on cost for surface translation; this is the sweet spot.
KJV 1769 + Synodal 1876	Bundled in the backend as JSON, served as the canonical scripture for the substitution layer. Public-domain, no API call.
Supabase Auth	Google OAuth + email/password. JWT verification server-side. The `auth.uid()` value flows through every RLS policy.
Datadog	Browser-RUM on the SPA, log intake from the FastAPI backend, four synthetics on the public surfaces. Free tier.
Resend	Transactional email (verify, password reset, certificate-ready notifications) from a verified `equipbible.com` domain. Free tier.
Sentry-class error attribution	Not Sentry itself — Datadog's RUM + log correlation does the same job for our scale, single vendor.

The pattern across all of these: pick a single best-fit service per layer, stay on free tiers as long as possible, never hide the integration behind a paywall.

What it does (the standard LMS surface)

Courses → modules → chapters, rich content via TipTap (callouts, audio, embedded YouTube, images), quizzes (multiple choice, true/false, short-answer, essay), assignments with a teacher grading queue, certificates with teacher approval, gradebook, cohorts, calendar, announcements.

The architecture, briefly

Layer	Stack
Frontend	React 18, TypeScript, Vite, Tailwind, shadcn/ui, TipTap, motion
Backend	FastAPI, Python 3.12, SQLAlchemy 2, Pydantic 2
Database	PostgreSQL on Supabase, RLS on every public table
Storage	Supabase Storage (avatars, course materials)
Deploy	Vercel — static SPA at equipbible.com, Python serverless at api.equipbible.com
CI/CD	GitHub Actions: lint, typecheck, 700+ backend tests, 220+ frontend tests, npm audit, pip-audit, Postgres schema smoke, CodeQL, OpenSSF Scorecard, Dependabot auto-merge for patch/minor
Monitoring	Datadog (RUM, logs, synthetics)

Total infra cost at current usage: $0. Vercel, Supabase, Datadog, and Resend free tiers carry the whole thing.

Mobile, too

No native app; responsive web from 360px wide. A native app is months of work that buys little at this scale.

State of production, 4 weeks in

Real numbers from the database as of this morning, not aspirations:

14 users (11 students, 2 teachers, 1 admin)
3 published courses, 1 in draft
10 modules, 28 chapters of actual content
21 enrollments across the 3 courses
6 chapters completed by active students
3 certificates issued (teacher-approved, full course completion)
9 quiz attempts submitted and graded

Each user signed up with a real email, enrolled in a real course, and in three cases finished one and received a teacher-signed certificate. End-to-end flow runs.

What's intentionally NOT there

No "Discover" feed or social layer. Students enroll because a teacher invited them, not because an algorithm recommended a course.
No live video conferencing. Use Zoom or Jitsi separately. Equip stores course-event entries with a meeting-URL field. That's the integration surface.
No mobile app. Responsive web works.
No monetization features. No paywalls, no premium tier, no "powered by" splash. MIT-licensed. Use it, fork it, deploy it.
No "AI assistant" widget. AI is in the translation pipeline as infrastructure, not in the UI as a feature. Bible-study students aren't asking for a chatbot.

How to actually use it

Two paths, depending on what you want:

Hosted at equipbible.com. Free. Sign up, you're in. Anyone can enroll in any published course. Teaching on the hosted instance is approval-based — the self-host path below has no such gate. No credit card.

Self-host your own instance. Clone the repo, point at your own Supabase project, deploy to Vercel. Bible schools that want their own URL, full data sovereignty, and isolation from other tenants get this. Total cost still $0 on the free tiers.

If you're a Bible school or ministry running coursework on Google Sheets and WhatsApp groups, this is for you. Either path works. Pick the one that matches how much technical setup you want to do.

What's next

Near-term on the published roadmap: teacher onboarding flow (the first-login /teacher page is too quiet right now), a completion-celebration moment (students don't know clearly when they finish a course), and a 15-minute self-host walkthrough for schools without a dev on staff.

Longer-term: more language pairs (Spanish + Portuguese for missionary contexts) via api.bible, in-platform certificate verification via signed JSON-LD, and a contribution path for translators to refine AI-translated content where wording matters most.

What I want to hear back

Especially from three groups:

Anyone running a small Bible school or ministry training program: what's blocking you from moving off your current setup? Particularly curious about Russian-speaking schools in CIS countries where the Synodal canonical-text handling matters.
Anyone who has built or contributed to a niche-domain LMS: what's the one constraint you wish you'd designed for from day one? I'd rather steal your lessons than learn them again.
Anyone considering forking Equip for a different niche (Sunday-school curriculum, a different religious tradition, secular adult-ed): tell me what'd need to change. Easier to plan the abstractions now than retrofit them later.

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 · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

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…

View on GitHub

76 RLS policies rewritten in one migration: the auth.uid() init-plan trap in Supabase

Vadym Arnaut — Wed, 20 May 2026 23:48:33 +0000

TL;DR. If your Supabase RLS policies call auth.uid() directly inside USING(...) or WITH CHECK(...), Postgres re-evaluates the function once per row. Wrap it as (SELECT auth.uid()) and the planner hoists the call to a single init plan that runs once per query. Same logical query, different plan, different cost at scale. We had 76 policies doing this wrong on Equip. Supabase's own auth_rls_initplan advisor lint found every one of them.

Equip is an open-source LMS we run on equipbible.com — FastAPI backend, React frontend, Supabase Postgres with RLS on every public table. Migrations live in the repo as plain .sql files. Standard setup, nothing exotic.

A while back we ran Supabase's database advisor as part of a pre-deploy sweep and one warning stopped us:

auth_rls_initplan: Detects RLS policies that re-evaluate
auth functions for each row.

It listed 76 of our policies. Same warning every time, same root cause.

What `auth.uid()` actually does per row

A typical Equip policy at the time:

-- BEFORE: auth.uid() called for every row scanned
CREATE POLICY "assignments_update_teacher" ON public.assignments
FOR UPDATE TO authenticated
USING (
  EXISTS (
    SELECT 1 FROM public.profiles p
    WHERE p.id = auth.uid()
      AND p.role IN ('teacher', 'admin')
  )
);

That auth.uid() looks like a constant. It isn't. It's a Postgres function marked STABLE, which means within one query it returns the same value, but the planner has to be told it can hoist the call out of the per-row loop. By default it doesn't. Every row scanned during the policy check fires the function again, allocates the JWT context, reads the claim, returns it.

For a 50-row dev table you'd never notice. For a chapter_progress table with one row per (student × chapter), or a quiz_answers table that grows every time a student submits anything, it adds up fast.

The fix that takes ten characters

-- AFTER: auth.uid() runs once, planner caches the result
CREATE POLICY "assignments_update_teacher" ON public.assignments
FOR UPDATE TO authenticated
USING (
  EXISTS (
    SELECT 1 FROM public.profiles p
    WHERE p.id = (SELECT auth.uid())
      AND p.role IN ('teacher', 'admin')
  )
);

Wrapping the call in a subquery isn't stylistic. The planner treats (SELECT auth.uid()) as a subquery returning one row of one value, and pulls it out into an InitPlan that runs exactly once at the start of the query. Every row check then sees a literal, not a function call.

You can confirm this on your own database. EXPLAIN ANALYZE on the bare version shows a function call inside the filter. On the wrapped version it shows InitPlan 1 at the top and the filter references $0. Same query, different plan.

Supabase covers this under RLS performance recommendations, but it's easy to miss when you're writing policies by hand at the same pace you're shipping features.

Why we missed it for months

Honest moment: we shipped most of Equip's policies with the raw auth.uid() pattern. They worked. Every test passed. Production users (students, teachers, admins) couldn't tell the difference. We were nowhere near the row count where the per-row overhead would have shown up as user-visible latency.

That's the actual trap. The warning sign isn't "your app is slow." By the time it's slow you've already shipped a pile more policies in the same shape, because everything you wrote between then and now had no reason to fail. The trap is that this pattern works fine in dev and on a small prod, then quietly compounds when one table grows.

Two patterns reliably hit the cliff first in our experience:

Per-user write tables like chapter_progress or quiz_attempts. One row per (student × content), grows linearly with engagement.
Many-to-many junctions like enrollments. Scanned during nearly every authenticated read.

Anything else (small lookup tables, course catalogs, taxonomy) stays fast for a long time even with the bad pattern. So the early "we don't see it yet" reading is correct, but it's not informative. The pattern is structurally wrong, you just haven't hit the row count that exposes it.

How we caught it: the database advisor

The Supabase project dashboard has an Advisors tab. Open it on any Postgres project and one of the performance lints is auth_rls_initplan. It scans pg_policies, parses the qual and with_check expressions, and flags any direct auth.<function>() call that isn't wrapped.

Two ways to run it:

# Supabase CLI (v2.81.3+)
supabase db advisors

# Or via the dashboard:
# https://supabase.com/dashboard/project/<ref>/advisors/performance

If you've wired the Supabase MCP server into your dev environment, get_advisors returns the same list as a tool call you can run from an agent. Either way the output is a flat list of policy names. The migration itself is mechanical:

-- For each flagged policy: DROP + recreate with the wrapped call
DROP POLICY "<name>" ON public.<table>;
CREATE POLICY "<name>" ON public.<table>
FOR <command> TO <roles>
USING (<original expression with (SELECT auth.uid())>);

Our 20260421015755_rls_perf_cleanup_016_policies.sql did this 76 times in a single migration. Mostly find-replace with care to keep the original semantics intact.

The PL/pgSQL footgun nobody mentions

While you're already in there, one more thing: if you've abstracted any of this into a helper function (e.g. is_admin() to keep policies DRY), check the language declaration.

-- BAD: planner can't inline a plpgsql function, every call is opaque
CREATE FUNCTION public.is_admin() RETURNS boolean
LANGUAGE plpgsql STABLE AS $$
BEGIN
  RETURN EXISTS (
    SELECT 1 FROM public.profiles p
    WHERE p.id = (SELECT auth.uid()) AND p.role = 'admin'
  );
END $$;

-- GOOD: SQL functions get inlined into the policy at plan time
CREATE FUNCTION public.is_admin() RETURNS boolean
LANGUAGE sql STABLE AS $$
  SELECT EXISTS (
    SELECT 1 FROM public.profiles p
    WHERE p.id = (SELECT auth.uid()) AND p.role = 'admin'
  );
$$;

LANGUAGE sql + STABLE + a single SELECT lets Postgres inline the function body into the policy at plan time. EXPLAIN looks identical to inline EXISTS. Switch to LANGUAGE plpgsql and the planner treats it as an opaque call. Can't push predicates in, can't reorder joins, every row hits the function.

We don't use helpers in Equip yet, but multiple people in the Supabase community have hit this when extracting is_member_of(school_id) for multi-tenant setups. The helper looks right, the policy looks DRY, the EXPLAIN looks wrong.

What to do today, in order

Open your project's Advisors → Performance tab. Look for auth_rls_initplan. If the list is non-empty, you have the trap.
Write a single migration that DROPs and recreates the flagged policies with (SELECT auth.uid()) everywhere auth.uid() appears bare. Don't try to refactor the policies' logic at the same time. Pure mechanical change.
While you're in the advisor, glance at multiple_permissive_policies and policy_exists_rls_disabled. Both compound the same per-row cost. Multiple permissive policies on the same role + action each run separately, so two bad policies double the trap.
If you have helper functions in policies, verify each is LANGUAGE sql STABLE with a single SELECT body. Convert any plpgsql ones if you can keep the logic in pure SQL.

The advisor keeps flagging this on every new policy you write, so once you wire it into pre-merge checks (CI step, pre-deploy hook, or a habit on PR review) the trap doesn't come back.

What I want to hear back, especially from people running Supabase in production:

Has this lint caught anything for you besides auth.uid()? auth.jwt() ->> 'role' should hit the same code path but I haven't traced it directly.
If you've written is_member_of(...) helpers for multi-tenant RLS, did you keep them in SQL or move to plpgsql? Curious about the tradeoff at scale.
For anyone who left these unwrapped on purpose — what does that constraint look like? I can imagine a few cases where you'd want the per-row eval, but I can't think of any in policy code specifically.

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 · Support · Changelog

Screenshots

Sign in (light)	Sign in (dark)
Account creation — student / teacher role picker	Mobile (390px)

Live at equipbible.com. Teacher and admin views (gradebook, course editor, analytics) are behind sign-in — create a free account to explore.

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…

View on GitHub

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?

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

There is no source language: a manifesto for symmetric multilingual content

Locale is just a column

What this fixes that you can name

What stays true from before

The principle, generalized

How to verify you have the same bug

Bigger than i18n

ArVaViT / equip

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

Equip

Screenshots

Why this project?

The auth_rls_initplan linter has a blind spot: SECURITY DEFINER bodies

What it doesn't see

The fix is the same wrap, one level deeper

How to find them

Equip: an open-source LMS for Bible schools — bilingual, scripture-aware, 4 weeks of real users

Why this exists

Bilingual content, end-to-end

The scripture-preservation constraint

What's wired in

What it does (the standard LMS surface)

The architecture, briefly

Mobile, too

State of production, 4 weeks in

What's intentionally NOT there

How to actually use it

What's next

What I want to hear back

ArVaViT / equip

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

Equip

Screenshots

Why this project?

76 RLS policies rewritten in one migration: the auth.uid() init-plan trap in Supabase

What auth.uid() actually does per row

The fix that takes ten characters

Why we missed it for months

How we caught it: the database advisor

The PL/pgSQL footgun nobody mentions

What to do today, in order

ArVaViT / equip

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

Equip

Screenshots

Why this project?

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.

What `auth.uid()` actually does per row

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