Future Classroom
A modern digital learning platform built for Georgian schools — Georgian first, English alongside — for a school with ~16 desktop learning workstations and one interactive touchscreen. AI helps where it is useful; nothing depends on it.
Technology should improve the learning environment, not replace the teacher.
Teacher → Lesson → Classroom session → Student activities → Hints → Feedback → Progress
- Teachers draft a lesson (with AI, or from built-in lessons when AI is off), edit everything, and run it live: students join with a code like
FC-4821, the teacher launches activities one by one and sees answers arrive in real time.
- Students answer on their workstation and get hint-first help: a conceptual nudge first, more specific hints next, and the full solution only as the last step (and only if the teacher allows it). Outside class they practise, take quizzes, review mistakes and work with the school's materials in the Learning Assistant.
- School materials (PDF, DOCX, TXT, Markdown) are indexed by their own chapters, sections and pages, and the Learning Assistant (
/learning-assistant) helps students work with them and with the lessons: explain a topic, find where the answer is, weigh the evidence for a statement, check their own understanding, find good questions and start a research project — always showing the source.
- Six laboratories that work without AI: Programming (Python and C++), STEM, Research, Critical Thinking, the School Library and Career & University — tied together by teacher assignments, a student portfolio and one learning profile per student.
- 18 subjects with a catalogue (
/subjects): 46 built-in lessons with practice, hint ladders and quizzes, each linked to the lab activities, simulations, books and career pages that fit it.
- Georgian and English throughout: the interface, the built-in lessons, the lab content and the demo school. Georgian is the default.
Quick start
Requirements: Node.js 20.9+ (22 LTS recommended).
npm install
npm run dev # http://localhost:3000
On first start in development (npm run dev) the app creates data/future-classroom.db, installs the built-in lessons and seeds a demo school (teachers, students, two finished sessions, quiz results, materials, lab work and assignments), written in the school's language — Georgian unless DEFAULT_LANGUAGE=en. No other setup is needed.
Demo accounts (password demo1234), or use the one-click buttons on the home page:
| Role | Username | Notes |
|---|
| Teacher | nino | Mathematics, economics, research, critical thinking; owns the demo sessions |
| Teachers | davit, eka | Physics, computer science, engineering · Chemistry, biology, geography, health |
| Teachers | manana, irakli, natia | Georgian, arts · History, civics · English, career |
| Student | mariam | Has progress history |
| Students | giorgi, ana, luka, saba, elene, nika, tamar | |
| Admin | admin | Can open any teacher's content |
Enabling AI (optional)
cp .env.example .env.local
# set ANTHROPIC_API_KEY=... (and optionally AI_MODEL, default claude-opus-5)
Without a key everything still works in offline mode, and the UI says so everywhere it matters (header badge, lesson notices, hint labels, Learning Assistant notes). The app never presents template content as AI output. The six laboratories use no AI at all: checking, feedback and hints are deterministic or teacher-written.
The 5-minute demo
- Teacher (normal window): Continue as demo teacher → Create lesson → Mathematics, Grade 11, “Quadratic equations” → Generate lesson.
- Review the lesson: tabs for structure (with a parabola graph), activities (each with a 4-step hint ladder and solution), discussion & homework. Edit anything, then Start classroom session → the join code appears.
- Student (private window or another workstation): open
/join, enter the code and a first name.
- Teacher: Launch first activity. Student answers the multiple-choice question.
- Teacher: Next activity (“Solve x² − 5x + 6 = 0”). Student clicks Get a hint twice (“What two numbers multiply to 6 and add to −5?”), submits a wrong answer, then the right one.
- Teacher sees the answer, attempts and hints used, clicks Show results to class, optionally opens Presentation view on the touchscreen.
- End session → the session summary (participation, correct %, common wrong answers, per-student table).
Also worth showing: Class overview (teacher insights), the student dashboard/progress, and the student Library (“What does our physics material say about Newton’s second law?”).
Subjects and built-in lessons
Subjects (/subjects) is the entry point for students and teachers: 18 subjects in six groups, filterable by grade and activity type. Each subject page has a recommended learning path, topics that link to real content (lessons, quizzes, programming problems, simulations, experiments, projects, library books, careers), the student's progress on each item and the lessons the school's own teachers have published. Teachers can preview or duplicate a lesson, assign any item, run it in a live session or start a new lesson for the subject.
| |
|---|
| Built-in lessons | 51 topics in all 18 subjects (src/lib/content/lessons/), written in Georgian and English side by side (Georgian literature in Georgian only): objectives, sections, 529 activities with hint ladders and solutions, 352 quiz questions (both languages counted). Georgian lessons use Georgian examples (lari, cities, history, literature) and Georgian units. |
| Installation | Built-in lessons are installed into every database at startup, including an empty one, and updated when the platform is updated (src/lib/db/builtin.ts). Teachers duplicate a lesson to adapt it. |
| Language | Each reader sees the version in their interface language; a link opens the other version. The interface language comes from the switcher, then DEFAULT_LANGUAGE, then the browser; Georgian is the fallback. |
| Terminology | src/lib/i18n/terminology.ts fixes the Georgian terms (and rules out calques such as „დაშბორდი“); tests/unit/terminology.test.ts checks every dictionary and every Georgian lesson and lab text against it. |
| Universities | No admission facts are stored as permanent truth: cards say when they were checked, warn after a year and link to official sites. |
The laboratories
All six labs are reachable from Labs in the navigation (/labs), plus Library (/library) and Career & portfolio (/career).
| Lab | What students do | How work is checked |
|---|
Programming (/labs/programming) | 30 bilingual problems in four levels (basics → algorithms), plus teacher-written ones: write code, predict output, find the bug. Python and C++. | Python runs in the student's browser (Pyodide/WebAssembly in a Web Worker, served from the school server — no internet needed). The server holds the test cases and compares outputs; hidden tests never reach the browser. C++ uses an optional Judge0 sandbox (JUDGE0_URL), otherwise students compile locally and paste their outputs (labelled self-checked). |
STEM (/labs/stem) | 8 classroom experiments (materials, safety, procedure, data table, conclusion), 7 simulations (projectile, motion, circuits, probability, linear model, growth, grid robot), electronics and robotics guides, engineering design projects. | Challenge questions are graded on the server with tolerances; experiment records reveal the expected results only after submission. Every item is labelled Simulation, Classroom experiment or Physical project. |
Research (/labs/research) | Question → hypothesis → sources → notes → evidence → data → analysis → findings → conclusion → presentation. Source quality checklist, quotations with attribution, evidence table, datasets with statistics and charts, generated bibliography, presentation mode. | Teacher feedback; quotations must be linked to a source (enforced on the server). |
Critical Thinking (/labs/critical-thinking) | Claim analysis, argument builder, fallacy identification (10 fallacies, taught for recognition, not manipulation), media literacy, debate mode with timer, intellectual humility. | Deterministic rubric feedback; progress per fallacy. |
School Library (/library) | Catalogue with filters, digital (openly licensed or school-owned) and physical copies, reading a book on the site — a Word file opens as Word shows it (fonts, colours, tables, page breaks; drawn in the browser, no internet needed), or as text with a contents, pages and search inside the book — next to downloading the school's copy, bookmarks, reading progress, questions answered from school materials. | Librarians print QR labels (/library/labels); scanning one opens the book page for that copy. Loans are recorded by staff. Four books ship with the platform, among them (hints and solutions in separate parts, so a student has to go looking for them). |
Teachers assign any lab item to a class or to students (/teacher/assignments), see who has started, handed in or finished, review work with feedback, and open each student's learning profile (/teacher/students). Lab items can also be run as a live classroom session (/teacher/sessions/labs).
The Learning Assistant
Future Classroom is the learning infrastructure; the Learning Assistant (/learning-assistant, in the main navigation, on the student home page, in the library and next to every searchable material) is one optional tool inside it. It is not a chatbot: it offers six learning tasks, phrased the way students ask —
| Task | What it gives |
|---|
| „ამიხსენი ეს თემა“ — explain this topic | Definitions, formulas and examples from the material, then the best passages; with AI, a short explanation whose every sentence is marked in the material, conclusion from the material, uncertain or not found in the material |
| „ამ მასალაში სად არის ამის პასუხი?“ — where is the answer? | The passages, with material, section and page, and the matching words highlighted |
| „რა მტკიცებულება აქვს ამ მოსაზრებას?“ — what is the evidence? | What kind of statement it is (general, causal, value judgement…), what it quietly assumes, the sentences of the material that match it, and claims, objections and replies found there |
| „შემამოწმე, სწორად გავიგე თუ არა“ — check my understanding | The student's own words compared sentence by sentence: matches, partly, check the numbers, may say the opposite, not found (which is not "wrong") |
| „რა კითხვები უნდა დავსვა ამ თემაზე?“ — what should I ask? | Questions built from the material's own definitions, formulas, claims and sections |
| „დამეხმარე კვლევის დაწყებაში“ — help me start research | Research questions to choose from, the sources found, what they do not cover, and a Research Lab project created with real quotations and their pages |
It searches only what the person may see (their materials by visibility, and published lessons — never activities, answers or solutions); a material can be chosen as the only source. Page numbers are shown only when the source has them. Without an AI key everything works; with one, only explain asks the model, only with the retrieved passages, and never for a question the material does not cover. Teachers can hand a research question or a set of questions to students as an assignment. The assistant also reads what a question is about ("what does afternoon mean?" searches for afternoon) and works as a dictionary over the school's English–Spanish book: the entry as printed (with its page in the reader), forms such as went → go, Spanish → English, spelling help, suggestions while typing, listening with the device's own voice, and My words — saved words practised with cards or by choosing the answer on a spaced-repetition schedule, kept in the visitor's own browser. Details and the design history: docs/LEARNING-ASSISTANT.md.
Running it in a classroom
The app is designed to run as one Node.js process on a school computer or small server on the classroom network; workstations and the touchscreen open it in a browser.
npm run build
npm start -- -p 3000 # then open http://<server-ip>:3000
npm run user:create -- --role teacher --username nbe --name "Nino Beridze"
npm run doctor # checks settings, database, backups, disk
Before real students use it, set OPEN_ACCESS=false (see below). A production build (npm start) with OPEN_ACCESS=false has demo sign-in and demo accounts off unless DEMO_MODE or SEED_DEMO is set to true. Anyone can create a student account with just a name and a password (/register; turn off with SELF_REGISTRATION=false); teachers can also create accounts on their class page and print sign-in slips.
Guides: docs/FIRST-LESSON-KA.md (one page, Georgian: install on a school computer, class, students, first lesson, classroom control) · docs/ACCESSIBILITY-AND-PERFORMANCE.md (WCAG AA scan, keyboard, Lighthouse results) · docs/CLASSROOM-CONTROL.md (one teacher computer guiding a class) · docs/LEARNING-ASSISTANT.md · docs/OPERATIONS.md (install, service, backups, accounts, updates, checklists) · docs/PILOT.md (a 45-minute pilot lesson, minute by minute) · docs/SECURITY-REVIEW.md · docs/DATA-ARCHITECTURE.md (SQLite assessment, PostgreSQL plan) · docs/CONTENT-ROADMAP.md · docs/LIBRARY-AND-UNIVERSITY-DATA.md · docs/AUDIT.md (pilot-readiness audit) · (12-week C++ programme, independent-learning framework, student projects and assessment; in Georgian) · (optional sign-up and sign-in with an email through Supabase: setup, flow, messages, privacy; in Georgian) · (Art & Creative Thinking: foundations, art history and Georgian art, photography, digital art, creative thinking, art + technology, projects, portfolio, assessment, site structure and a 12-week programme; in Georgian).
- Data lives in
data/ (SQLite database + uploaded files). npm run backup makes a checked copy while lessons run; npm run restore brings one back.
- Real-time updates use Server-Sent Events with automatic polling fallback, so sessions keep working behind proxies or on unstable Wi-Fi; student drafts are kept in the browser.
- Serve over HTTPS if the network allows it (
COOKIE_SECURE=true).
- Run a single instance (the real-time channel and rate limiter are in-process).
- Set
PUBLIC_BASE_URL (e.g. http://192.168.1.10:3000) so the join address on the projector, account slips and library QR labels show the address workstations and phones actually use. Without it the server uses the request's address, replacing localhost with its own network address.
- C++ checking on the server needs a Judge0 instance you run yourself (
JUDGE0_URL, optionally JUDGE0_TOKEN). Student code is never executed by the Future Classroom server itself.
Open access and Vercel
Open access is on by default (OPEN_ACCESS): there is no sign-in and no registration. The home page offers two choices, "demo teacher" and "demo student"; the page then greets "Hello, teacher!" or "Hello, student!", and a button in the header switches the view. A link to an inner page lets the visitor straight in as the view that part of the site is for (teacher pages: teacher; everything else: student). The choice is kept in a cookie (fc_open), nothing about it is stored on the server, so any server instance can serve the visitor. Everyone who opens the site works as the same demo account: they all see (and can change) the same data. That is right for showing the platform and wrong for a school with real students: set OPEN_ACCESS=false and the platform's own sign-in (and Supabase sign-in, when configured) is back; npm run doctor reports open access as a problem.
On Vercel the app runs as it is, with these differences from a school server:
- The deployment is read-only, so the database and uploaded files go to the instance's temporary folder (
/tmp/future-classroom; DATABASE_PATH and UPLOAD_DIR still override). The demo school is created on the instance's first request (about 2 seconds), so what visitors change is private to one running instance and is lost when Vercel replaces it, and two visitors may be served by different instances. The seeded demo content is the same everywhere. Lasting, shared data needs a database outside the instance (see docs/DATA-ARCHITECTURE.md).
- Live lessons use in-process messaging with polling as the fallback; on a platform that runs several instances, a teacher and the students of one lesson may land on different instances and not see each other. Run live lessons on a school server, or on a single always-on process.
- A request body is limited to 4.5 MB: larger material uploads fail.
- The Pyodide files (Python in the browser) are copied to
public/pyodide by npm run build (the prebuild script) so Vercel serves them as static files; the built-in books are included in the deployment through outputFileTracingIncludes in next.config.ts.
- No environment variables are needed. Set
ANTHROPIC_API_KEY for the AI features and DEFAULT_LANGUAGE=en for an English demo.
Today: a reason to come back
/today is open to everyone (no account needed) and is built to be opened every day:
- The daily challenge: one question a day, the same for everybody, new at midnight (Tbilisi time). Each weekday has its own kind of question (Monday numbers, Tuesday science, Wednesday code and tech, Thursday thinking sharp, Friday a surprise from any subject, Saturday our world, Sunday life skills), taken from the built-in lessons and quizzes, so a week is a small course and a question comes back only after every other question of its kind. Three tries: hints after wrong answers, the answer after the third. It is graded on the server (
/api/daily/check); the page never carries the answer, hints or explanation, and the check needs no database, so it works on any host.
- Study streak, experience points, levels, achievements, an activity map and three daily goals (finishing all three earns a bonus). They come from the challenge and from real activity anywhere on the platform: correct practice answers, finished quizzes, live-class answers and joins, work in a laboratory (
src/lib/engagement/api-events.ts decides what counts). Showing up counts: a missed challenge still keeps the streak. Wrong tries, answers and the result are plain: no confetti, no cartoon characters; a thin light crosses the top of the window when something is earned.
- It is the visitor's own and lives in their browser (localStorage,
src/lib/engagement/model.ts is the whole game and is unit-tested). It needs no account, works with open access (where everyone shares one demo student), survives a host without a database, and is not a grade: the teacher does not see it. The privacy page says so. Share button: a result to paste to friends, without the answer.
- For teachers: Start with today's challenge on the teacher dashboard puts the question on the classroom display (
/present/daily) with hints and the answer behind buttons.
Look: black and premium with one red. Everything takes its colours from the tokens at the top of src/app/globals.css (canvas, surface, ink, line, brand for text and strokes, brand-solid behind white text, glow-a/b/c for the moving red lights), so the whole site changes in one place. .theme-light puts the original white page back inside a region (the projector's light mode, the research presentation) and printing always uses it, so worksheets, sign-in slips and QR labels stay black on white.
Motion (src/app/globals.css, src/components/motion/): one language everywhere. Content rises into place with a soft focus pull (.fc-rise, staggered with --i), sections arrive as they scroll into view (.fc-reveal, tied to scroll where the browser can), numbers count up in pure CSS (CountNumber), the dark panels (Aurora) drift slowly, cards light up around the pointer (.fc-spotlight, one listener in SpotlightPointer), the navigation underline slides between items, and a page rises in when the address changes (PageTransition). It all collapses to a still page under prefers-reduced-motion.
SCHOOL_TIMEZONE (an IANA name, default Asia/Tbilisi) decides where the day changes. About half of the built-in questions have no written explanation yet, so the "Why" panel is missing for them: adding explanations to the lessons in src/lib/content/lessons/ improves the challenge directly.
Architecture
| Layer | Choice |
|---|
| Web app | Next.js 16 (App Router, React 19, TypeScript, Turbopack), Tailwind CSS v4 |
| Data | SQLite via better-sqlite3 (WAL), schema migrations in src/lib/db/schema.ts |
| Search | SQLite FTS5 over stemmed terms (Georgian suffix stemming, bilingual synonyms, typo tolerance), re-ranked by BM25, question coverage, section names and extraction quality |
| Real-time | Server-Sent Events + in-process event bus; clients re-fetch their own view |
| AI | Provider-neutral AIProvider interface; Anthropic implementation via the official SDK (structured outputs) |
| Auth | Username/password (scrypt), server-side sessions in SQLite, httpOnly cookies; roles from the database only |
| Tests | Vitest (unit + service tests on in-memory SQLite), Playwright (end-to-end flows for every lab, offline, multi-tab and screen widths) |
src/
app/ routes (pages + /api route handlers)
teacher/ dashboard, lessons, sessions (live console), quizzes, materials, insights
subjects/ subject catalogue and subject pages
student/ dashboard, learn (topic: learn/practice/quiz/ask), progress, library
session/[id] student live-session screen
present/ touchscreen presentation (live session, lesson slides, research)
labs/ lab hub, programming, stem, research, critical-thinking
library/, career/ School Library (catalogue, QR labels) and Career & University
portfolio/[userId] portfolio overview for teachers and mentors
components/ UI (ui/ primitives, lesson editor, session console, student views, …)
lib/
ai/ AIProvider, Anthropic provider, lesson/quiz generators, hint service,
tutor, built-in lesson templates (EN + KA)
knowledge/ Georgian/English word matching, synonyms, document ingestion (cleaning,
structure, page-aware passages), knowledge extraction, claim checking
services/ lessons, quizzes, sessions, materials, knowledge search, Learning Assistant,
progress, users,
assignments, classes, portfolio, feedback, attachments, learning profile
labs/ one folder per lab (content catalogues, graders, services),
session bridge and assignment registry
domain/ zod schemas, grading, ids/join codes, safe math-expression parser
db/ connection, schema, demo seed
content/ built-in lessons (EN + KA), subject catalogue and its resolver (library books: content/books/, their sources: content/books-src/)
i18n/ en.ts (source of truth), ka.ts (type-checked against en), terminology
files/ upload validation, text extraction (PDF lines, DOCX headings)
http/, auth/, realtime/
tests/unit, tests/e2e, tests/e2e-supabase
Key design decisions
- Teacher control. AI output is always a draft. Regenerating a section/activity replaces it in the editor only (with undo) until the teacher saves. Publishing an AI lesson requires confirming it was reviewed.
- Hint-first.
lib/ai/hint-service.ts serves teacher-written hints first, then AI hints (cached per activity and level, so a whole class asking costs one model call), then clearly-labelled generic strategies. Level 5 (full solution) exists only if the teacher allows it.
- No answer leaks. Students' session and practice payloads never include answer keys, hints they have not unlocked or solutions; answers are checked on the server.
- Honest AI. Every AI-dependent feature has an offline path and says which path was used. The Learning Assistant shows the material's own text with its source; an AI explanation is checked sentence by sentence against the passages it was given, and anything they do not carry is marked as such. AI never fills the lesson sources field.
- Snapshots. A classroom session copies its activities at start, so editing a lesson later never changes past results.
- Privacy. Students need only a first name; tutor conversations are not stored; the only behavioural data kept is which questions were answered and whether correctly (see
/privacy).
Scripts
| Command | What it does |
|---|
npm run dev / build / start | Next.js |
npm run typecheck / lint / test | TypeScript, ESLint, Vitest |
npm run check | All three of the above |
npm run test:e2e | Builds, starts a fresh demo server with AI disabled and OPEN_ACCESS=false (so sign-in is tested) and runs the Playwright suites (set PLAYWRIGHT_CHROMIUM_PATH to use a system Chromium, E2E_SKIP_BUILD=1 to reuse the last build) |
npm run test:e2e:supabase | The email sign-up and sign-in flow in a browser against a stand-in for Supabase (tests/e2e-supabase/); same options as test:e2e |
npm run test:e2e:open | The site in open-access mode (the default): two choices (demo teacher, demo student), no sign-in or registration |
npm run db:reset | Recreate the database with demo data (-- --empty for none) |
npm run user:create | Create a teacher/student/admin account |
npm run user:password | New temporary password for an account (-- --username x), or -- --list |
npm run backup / restore | Checked backup of database and uploads (safe while running) / restore one (server stopped) |
npm run supabase:check | Checks NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY and asks the project whether the key is accepted, sign-ups and email confirmation are on and which redirect URL to allow (only the public key is used) |
npm run doctor | Health check: settings, database integrity, demo passwords, backup age, disk space |
npm run materials:reindex | Re-read uploaded files and rebuild their passages and knowledge (-- --all for every material); older materials are otherwise upgraded automatically at start-up |
npm run drill | Real browsers against a throwaway server: duplicate tabs, slow network, reloads, server restart mid-lesson |
Configuration
See .env.example: ANTHROPIC_API_KEY, AI_MODEL, DATABASE_PATH, UPLOAD_DIR, SEED_DEMO, DEMO_MODE, SELF_REGISTRATION, BACKUP_DIR, DEFAULT_LANGUAGE (ka or en: the school's default interface language and the language of the demo data), COOKIE_SECURE, PUBLIC_BASE_URL, JUDGE0_URL, JUDGE0_TOKEN, JUDGE0_PYTHON_ID, JUDGE0_CPP_ID, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY (optional email sign-up and sign-in through Supabase; see docs/SUPABASE-AUTH.md), SCHOOL_TIMEZONE (where the school day changes; default Asia/Tbilisi), OPEN_ACCESS (on by default: no sign-in at all, visitors choose the demo teacher or demo student view; OPEN_ACCESS=false brings sign-in back for real students).
Known limitations
- Search is lexical (stemmed words, synonyms, typo tolerance), not semantic: a question in completely different words from the material can miss. The synonym table covers common school terms only. Scanned PDFs without a text layer are stored and reported as needing OCR, but are not searchable (no OCR is included).
- Heading, definition and claim detection is heuristic. It is conservative and never invents text or pages, but it can miss structure in unusually formatted documents.
- Classes are simple rosters (add/remove students, create accounts, reset passwords, class progress); there is no full school-administration console, no timetable and no gradebook export.
- Programming tests check output only (no memory or strict performance limits beyond a per-test time limit in the browser). Without Judge0, C++ results are self-reported and labelled as such.
- STEM simulations are simplified models for teaching (no air resistance, ideal components); physical experiments and robotics projects need real materials and kits the school provides.
- Single-process deployment (in-memory event bus and rate limits).
- The Georgian texts were reviewed for natural wording and consistent terminology, but subject teachers who are native speakers should still read the built-in lessons before classroom use, especially literature and history.
- Starter content is a base, not a full curriculum: most subjects have 2–4 built-in lessons (computer science 7, physics 6), and arts, engineering, entrepreneurship and career one each. No built-in lesson has been through the school's review workflow yet; see docs/CONTENT-ROADMAP.md for gaps and order.
- The demo library catalogue and university cards are demo data; a real school enters its own.
- University cards contain only what students and teachers enter; the four shared demo cards have no admission figures on purpose.
