SAT Ustoz: SAT practice site
A static site for GitHub Pages. No build step, no server except the optional Cloudflare Workers (AI and payments).
index.html Landing page (EN / UZ / RU)
practice.html Practice hub: dashboard with the Score Gap Analyzer, study plan, progress graph, Mistake Bank (#mistakes), settings and Telegram (#settings), practice sets, drill builder, AI practice, tests
test.html Adaptive practice test in the digital SAT format (test.html?id=<test-id>)
login.html Sign in / register with Google, plus a short first-time profile form
builder.html Question builder for your team (not linked from the site, hidden from Google)
admin.html Approve card-transfer payments, reports, invite rewards, mocks, teachers, real scores (for you only, hidden from Google)
vocab.html Vocabulary trainer: SAT words with Uzbek and Russian meanings, spaced repetition, works offline
lessons.html 5-minute skill lessons in EN / UZ / RU, each with a 5-question check
daily.html Question of the day (counts toward the one streak, section 10)
score-calculator.html Public SAT score calculator (EN / UZ / RU), aimed at the search "SAT ballini hisoblash"
mock.html National mock: countdown, then the leaderboard by region and school
teacher.html Classes, homework, results grid and parent reports, for teachers on the center plan
sat-tayyorgarlik.html, sat-test-onlayn.html Uzbek landing pages for the searches "SAT tayyorgarlik" and "SAT test onlayn"
sw.js Offline support (keeps the vocabulary trainer working without a connection)
404.html Branded "page not found" page (GitHub Pages uses it automatically)
assets/sh.css Brand styles (colours and fonts at the top)
assets/sh.js Shared code. SETTINGS block at the top: AI_ENDPOINT, FIREBASE, REQUIRE_LOGIN, ANALYTICS, PLANS, PAYMENTS_ENDPOINT, TESTS_ENDPOINT, MANUAL_PAY, contacts
data/catalog.json List of every practice set and practice test
data/vocab.json The vocabulary list (word, part of speech, English, Uzbek and Russian meaning, example)
data/lessons.json The lessons (text in EN / UZ / RU, and which practice set their check uses)
data/testimonials.json Student quotes and scores on the landing page
data/calibration.json How close practice scores are to real SAT scores (copied from admin.html)
data/sets/*.json Practice sets
data/tests/*.json Practice tests 1 to 3 and the mini diagnostic (Pro Tests 4 to 10 belong in a private repository, section 6)
worker/ai-worker.js Cloudflare Worker that holds the AI key (not used by the pages directly)
worker/payments-worker.js Cloudflare Worker for Payme payments, monthly renewals and the Pro test files
worker/telegram-worker.js Cloudflare Worker for the Telegram bot: weekly reports, reminders, parent reports, question times
firestore.rules Database security rules to paste into Firebase
tools/check_test.py Checks a test file before you upload it (no need to upload this folder)
robots.txt, sitemap.xml
1. Deploy
- On GitHub, open the repository and choose Add file → Upload files.
- Drag in everything from this folder (the
assets, data and worker folders too) and commit.
Uploading replaces index.html, robots.txt and sitemap.xml.
- Keep
CNAME. It is not in this folder and keeps your domain working.
The old logo.jpg is no longer used. The logo now lives in assets/brand/, and you can delete
logo.jpg from the repository.
- Wait a minute or two, then open satustoz.academy and run through: practice set, the mini
diagnostic test, and the language switch.
The site works fully at this point. Until step 2, the AI practice tab shows a "not switched on yet" note and the
AI tutor buttons stay hidden.
2. Switch on the AI (about 10 minutes, free tier is enough)
The AI key must never be in the website. Anything in a page is public, the same problem the old
Telegram bot token had. The Worker keeps the key on Cloudflare's side.
- Create an API key at console.anthropic.com and set a monthly spend limit there.
- Follow the steps at the top of
worker/ai-worker.js: create a Worker, paste the file, add the key as
a Secret, add ALLOWED_ORIGINS, and (recommended) bind a KV namespace as RATE_LIMIT so each
student gets a daily limit.
- Put the Worker URL in
AI_ENDPOINT at the top of assets/sh.js and upload that one file again.
Models: question writing uses claude-sonnet-5-5, the tutor uses claude-haiku-5-5 (cheaper, fast).
Change them with the GEN_MODEL and TUTOR_MODEL variables in Cloudflare, no code change needed.
Who gets the AI. Free and Pro students get FREE_DAILY_AI tutor questions a day (default 3, counted per student
in the RATE_LIMIT KV, reset at midnight Tashkent time). Max students get an unlimited tutor (up to DAILY_LIMIT, a
safety cap) and are the only ones who can generate new AI practice questions. The Worker reads the student's plan and
planUntil from Firestore using the student's own sign-in, so it needs FIREBASE_PROJECT_ID and the RATE_LIMIT KV
binding, and no extra key. To change the daily number, edit FREE_DAILY_AI in Cloudflare (the site's wording says 3:
search 3 AI tutor / 3 free in assets/sh.js, practice.html and index.html if you change it).
Max goes on sale when the AI is on. With AI_ENDPOINT filled in, the Max card shows "Get Max" (card transfer, the
same steps as Pro, at MAX_PRICE), and the landing page switches from "AI tutor coming with Max" to the live wording.
admin.html approves Max requests like Pro ones. Message the Max waitlist (admin.html, "Copy all usernames") the day you
switch it on. Max includes a monthly live group session with you: plan the first one before the first sale.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
