IYT Test

IYT Test

Practice questions for IYT certification levels — a Telegram mini app and a website. Every question is a situation ("you see this mark ahead — where is the safe water?"), drawn as a figure where it can be, with four options and a one-line note naming the rule. First level: Bareboat Skipper (100 questions, 10 topics).

Status (2026-11-02): design and question bank done; the Telegram mini app (practice, mock exam, progress, profile) and a small bot are built and deployed (Vercel). Website not started.

What is in the repo

README.md                       this file

docs/ PLAN.md goal, decisions, next steps question-bank.md JSON format of a bank, authoring rules, how to build it figures.md the figure spec: every type, its fields, an example figure-style.md the agreed look of the rendered figures (cameras, looks, own boat, lights, annotations) design.md look & feel, components, the 21 screens, how to use the viewer data-model.md proposed database (Supabase) and how progress is computed theory.md the theory articles: format of an article, authoring rules, check and build superpowers/plans/ implementation plans (theory articles: 2026-11-05-theory-articles.md) design/ flows.html hi-fi user flows (viewer: pages / overview, day / night) questions.html the whole bank as the student sees it, filter by topic flows.css flows.js viewer + test UI pieces app.css app tokens and base components (day and night) test-icons.js the app's icon set (24 grid, 2 px line) + svg()/paintIcons(), shared by the viewer and the app icons.html the icon sheet: every glyph at 24 px and in the topic circle, day / night icons.js older base set (Telegram chrome in the mockups; a few basics follow Lucide) figures.js figure generator (JSON spec → SVG) figure-style-spike.html reference renderer for figure-style.md (three.js from a CDN; open over HTTP) figure-schematic.js plan-view schematic renderer (the companion diagram to every realistic figure) figure-style/ sample renders of the ten example questions; hires/ at 2560 × 1600, schematic/ their plan views logo-black.svg RYC logo data/ build_bank.py source of the Bareboat Skipper bank — edit here, then run build_level.py builds the other levels from bank/ / .json (+ .ru.json) bank/ / .json VHF Radio Operator, International Crew, Flotilla Skipper: 20 questions per topic; Charter Check-in: 50; Yachtmaster Coastal, Offshore and Ocean, Racing Rules of Sailing: 100 questions/ .json the built banks the apps read questions/ .ru.json Russian translation of each bank (overlay) i18n.py extract strings to translate / check an overlay theory/ / .json theory articles, one per topic of every level (+ .ru.json): 90 in all, each with figures check_theory.mjs checks the articles against docs/theory.md and the banks (npm run check:theory) miniapp/ index.html app.js app.css the Telegram mini app (static, no framework, no backend) build.mjs builds miniapp/dist (the folder to host): the app, design files, fonts and minified banks, each linked file renamed after its content (h/…) so phones cache it for good, and the list of banks written into index.html so only the current level's bank loads at start fonts/ Merriweather and Carlito (woff2, Latin + Cyrillic, OFL), served with the app pages.mjs site.css the site around the app: a page per level and per theory article (EN + RU), sitemap, llms.txt site.mjs the public address, the bot and the IndexNow key indexnow.mjs npm run seo:ping: tells Bing and Yandex which pages changed bot/ core.mjs the bot's replies: /start /exam /progress /settings open the app, /daily asks a question daily.mjs the daily question of the day to everyone who has it on bot.mjs runs core.mjs by long polling (local testing) scripts/setup.mjs sets the bot's name, descriptions, commands and menu button scripts/webhook.mjs points Telegram at the Vercel webhook, or removes it api/ telegram.mjs Vercel function: Telegram's webhook, runs core.mjs daily.mjs Vercel cron (09:00 UTC daily): runs bot/daily.mjs settings.mjs the app's question-of-the-day switch (users.daily_question), checked with Telegram initData admin.mjs every student's results, flagged and reported questions (admins can take a flag off), joins/answers/wrong answers per hour and day for the admins (ADMINS in settings.mjs — @fullcrimp; ADMIN_USERNAMES adds more) mcp.mjs the MCP server: the banks and the theory articles as tools for AI assistants (public, read-only)

Mini app

npm run dev                     # http://localhost:5173 — works in a normal browser too

Screens follow docs/design/flows.html: A1–A9 practice (set-up sheet, Check → why → Next, results, mistakes), B1–B5 mock exam (40 questions spread over all topics, timer that pauses while the app is closed, flag + grid, pass/fail), C1 progress, C2 profile (theme, shuffle, reset). Mastery = right twice in a row. Progress is saved per user in Telegram CloudStorage (localStorage in a browser), so there is no server or database yet. Inside Telegram the app uses the native Back, Main and Secondary buttons and haptics; outside it draws the same bar itself. Deep links: ?screen=exam|progress|profile|practice|level, or startapp= with the same values. Languages: English and Russian interface (follows the Telegram language until switched in Profile; the choice is saved, like the theme). All 1000 questions are translated in data/questions/bareboat-skipper.ru.json (terms: docs/glossary-ru.md); see docs/question-bank.md.

It is live at https://iyt.rycrentals.com and connected to @iyt_test_bot: the bot's menu button opens the app, and the bot itself runs as a webhook on the same Vercel project (api/telegram.mjs). To set it up again from scratch:

1. Put TELEGRAM_BOT_TOKEN, WEBAPP_URL and TELEGRAM_WEBHOOK_SECRET (openssl rand -hex 32) in .env.local, and the same three in the Vercel project's Production env.
2. npx vercel deploy --prod — builds miniapp/dist and deploys the webhook function next to it.
3. npm run bot:setup — name, descriptions, commands, menu button → the app. Then make it the bot's Main Mini App in @BotFather (Bot Settings → Configure Mini App → Enable Mini App, send WEBAPP_URL): the bot's profile gets an Open button and t.me/iyt_test_bot?startapp= links open the app straight away. Telegram has no API for this; npm run bot:setup -- --check shows whether it is on.
4. npm run bot:webhook — tells Telegram to send updates to WEBAPP_URL/api/telegram (-- --check shows its state).

To try bot changes locally: npm run bot:webhook -- --delete, then npm run bot (long polling), and npm run bot:webhook again when done — Telegram delivers to a webhook or to polling, not both.

Question of the day

Every day (Vercel cron, 0 9 * * * UTC — 13:00 Dubai, 12:00 Moscow) the bot sends one text question with A–D buttons to each user who has it on; the answer and the note come back in the same message. Everyone gets the same question that day. The bot saves each user who writes to it in Supabase users (daily_question on by default).

• Per user: a switch button under the daily question and in /settings ("Question of the day: on/off").
• Whole bot: DAILY_QUESTION=off in the Vercel env stops the send for everyone (users' own switches stay).
• Users who block the bot are marked (blocked_at) and skipped until they write again.

Needs on Vercel: SUPABASE_URL, SUPABASE_SECRET_KEY, CRON_SECRET (openssl rand -hex 32), and the migration supabase/migrations/20261102150000_daily_question.sql. Try it: npm run bot:daily -- --to (add --ru for Russian) sends today's question to one chat; npm run bot:daily -- --dry counts who would get it.

Not in this version (needs the Supabase backend in docs/data-model.md): DE/ES, the streak reminder, cross-device sync with the website, theory notes, the share image.

Search engines and AI assistants

Search engines and most AI crawlers read a page without running its JavaScript, so next to the app the build writes the site as plain pages (miniapp/pages.mjs, styled by miniapp/site.css over the app's own CSS), at https://iyt.rycrentals.com (SITE in miniapp/site.mjs):

Every page has its own title and description, a canonical link, hreflang links to its other language, link preview tags and structured data (breadcrumbs; Article and Quiz on a topic). Nothing is written by hand but the strings in pages.mjs: a new article or a new level gets its pages on the next build. A section's opener (qa in docs/theory.md: the question a student would ask, answered in a sentence or two) goes under its heading and into the page's FAQPage data, the passage search engines and AI assistants quote. The build also writes robots.txt (AI crawlers named and let in, search and training alike: the content is free and the MCP server gives it out anyway), sitemap.xml (every page with its other language), llms.txt (the site's map for AI assistants), 404.html, the IndexNow key file and pages.json (each address with a hash of its page). npm run dev serves the pages at their clean addresses, as Vercel does (cleanUrls).

After a production deploy:

• npm run seo:ping tells Bing and Yandex (IndexNow) which pages are new, changed or gone since the last ping (the live pages.json against miniapp/.indexnow-sent.json, which is not in git); -- --dry lists them, -- --all sends every page, -- --check only checks the key file is live.
• Once, by hand (each needs your account): add iyt.rycrentals.com in Google Search Console, verify it with the DNS TXT record it gives (on the rycrentals.com zone), and submit sitemap.xml; then Bing Webmaster Tools → Import from Google Search Console; then Yandex Webmaster → add the site, verify (DNS or meta tag), add the sitemap.

MCP server

api/mcp.mjs gives the question banks and the theory articles to AI assistants (Claude, ChatGPT and anything else that speaks the Model Context Protocol): a student adds https://iyt.rycrentals.com/api/mcp as a remote MCP server (a custom connector) and practises in their own assistant. It is public and read-only: no sign-in, nothing is saved, and it returns only what the app already serves. How to connect it is on ht