Bilingual content catalog for traffic rules and road signs

The driving theory platform needed more than a question bank — it needed the entire body of traffic rules, organized, searchable, and readable in both Russian and Uzbek. In this market, the PDD (pravila dorozhnogo dvizheniya — the official traffic rules document) is the legal foundation for every exam question. Students don't just memorize answers; they need to understand the rules those answers come from. On top of that, there are over 200 road signs, each with an official image, a legal description, a category, and context about where and how it applies. All of it needed to be served through an API to a Telegram Mini App frontend — fast, structured, and always in sync with the current law.

hierarchy and cross-references

We built the PDD catalog as a hierarchical content system: chapters contain numbered points, and each point can include rich text, inline images, and cross-references to other points or to specific road signs. The cross-referencing part was the critical design decision. Traffic rules don't exist in isolation — a rule about yielding at intersections references rules about traffic light signals, which reference rules about road markings. We modeled these as explicit typed relations in the database rather than embedding links in the text body. That way, when a rule gets updated or renumbered (which happens when legislation changes), the references update automatically instead of becoming dead links scattered across hundreds of content entries.

road signs at scale

The road signs database was a separate beast. Over 200 signs, each needing a clean image at consistent dimensions, a category (prohibitory, warning, informational, priority, and so on), and full descriptions in both languages. The images came from official sources but in wildly inconsistent formats — different resolutions, different background treatments, some as photos of physical signs rather than clean vectors. We standardized everything into a uniform format with consistent padding and transparent backgrounds, served as static files with predictable paths. The API returns sign metadata with image URLs, and the frontend renders them in a filterable, categorized grid. Simple, but getting 200+ images to look uniform took more manual effort than we expected.

translation review workflow

The translation layer is where this project either works or falls apart. Traffic rule text isn't casual content — it's legal language where a single ambiguous word can change meaning. We couldn't rely on machine translation or even casual bilingual review. The system stores Russian and Uzbek content as parallel entries tied to a shared canonical ID, with a status field per translation: "approved," "draft," or "needs review." When the Russian source text changes (because the law was amended), the corresponding Uzbek entry automatically moves to "needs review" status. The admin panel surfaces these mismatches as a prioritized work queue, so translators always know exactly what's stale. This prevented the most dangerous failure mode: serving confidently wrong translations of legal content.

versioning when laws change

Content updates deserve their own mention because they're the ongoing reality of this system. Traffic laws change — sometimes a single point, sometimes an entire chapter restructured. The architecture needed to support partial updates without breaking the web of cross-references. We achieved this through versioned content entries: each point has a version number, and cross-references point to the canonical ID rather than a specific version. When content updates, the system creates a new version while keeping the old one accessible for users who started studying under the previous ruleset. It's a small detail, but it prevents a frustrating experience where a user's bookmarked rule suddenly says something different than what they studied yesterday.

one source of truth

The result is a content system that serves as the authoritative reference layer for the entire platform. Questions in the learning engine link back to the relevant PDD points. The AI consultant (a separate module) queries the same content when explaining rules. Road signs appear contextually when relevant to a question. Everything feeds from one source of truth. The takeaway here was about respecting the weight of the content. This isn't a blog or a product catalog — it's legal text that people rely on to pass a government exam. The extra rigidity in the translation workflow and the versioning system felt like over-engineering at the start, but every time a law changed mid-semester, we were glad it was there.

Backend: FastAPI, PostgreSQL

Content: hierarchical chapter/point model, typed cross-references, versioned entries

Media: static file serving with standardized image pipeline

Translation: parallel bilingual entries with status-based review workflow