iAmTeacher

iAmTeacher (pronounced "I am teacher") is an AI-powered English tutor app for students in rural areas, where most of them lack capable English teachers. This app focuses on vocal conversations, while also including written quizzes and other educational activities.

How It Works (Conversation)

The vocal conversation parts work with OpenAI's Realtime API services. We give it a system prompt, and these steps happen during a conversation:

1. Student starts the conversation.
2. The frontend connects to OpenAI's Realtime API via WebRTC, using an ephemeral key generated by the backend.
3. What the student says is transcribed into the LLM's input.
4. The LLM's output goes through Text-to-Speech and plays on the student's device.
5. Steps 3–4 repeat until the conversation goals are accomplished.

Features

• Multiple tuition/teaching styles to choose from
• Tailoring content according to student's skill level and learning goals
• The possibility of using alternative voice recognition, LLM, and TTS platforms
• Role-based access: student, teacher, and admin
• Teacher dashboard for monitoring student progress and conversations
• Token usage tracking per student and per session
• Terminal-based admin panel (TUI) for user and system management

Requirements

• Node.js (v18 or later recommended)
• SQLite3 must be installed on your machine — better-sqlite3 compiles a native binding against it

Install SQLite3 if you don't have it:

# Ubuntu / Debian
sudo apt install sqlite3 libsqlite3-dev

# macOS (usually pre-installed, or via Homebrew)
brew install sqlite3

# Windows
# Download from https://www.sqlite.org/download.html

Setup

Before you begin, you'll need an OpenAI API key — create one here.

Clone this repo:

git clone https://github.com/zymple/iamteacher.git
cd iamteacher

Create a .env file from the example and set your values (see .env.example):

OPENAI_API_KEY=<your_openai_api_key>
DEBUG=True # USE DEBUG TRUE ONLY FOR DEV
VITE_ALLOWED_HOSTS=localhost,127.0.0.1
LOGGING=True # USE LOGGING TRUE ONLY FOR DEV
BASE_URL=http://localhost:3000 # CHANGE TO YOUR PRODUCTION SERVER URL

Install dependencies:

npm install

Start the server:

npm start

This will start the application on http://localhost:3000.

Creating Your First Users

There are no default accounts. You must create your first admin account using the Admin TUI, then create teacher and student accounts from there.

node admin-tui.js

Select option 2 (Create new user), enter an email and password, and choose the admin role. Then create teacher and student accounts as needed.

See docs/admin-tui.md for the full TUI guide.

Migrating from the Old .txt Config

If you're upgrading from an older version that used config/user.txt for user credentials, the migration is automatic. On first startup, if app.db doesn't exist but config/user.txt does, the server will:

1. Create a new SQLite database (app.db)
2. Import all users from config/user.txt into the database

Important: All migrated users will be assigned the student role by default. You'll need to use the Admin TUI to promote users to teacher or admin:

node admin-tui.js
# Select option 5 (Change user role)

The old config/user.txt, userdata/, and logs/ directories are no longer used after migration. You can archive or delete them once you've confirmed everything works.

Documentation

• docs/api.md — Full API reference for frontend developers. Covers every endpoint with example requests, responses, pagination, and role permissions.
• docs/admin-tui.md — Guide for the terminal-based admin panel. User management, student progress monitoring, log viewing, and token usage tracking.

Contributing

Frontend contributors — Read the API docs at docs/api.md to understand all available endpoints, authentication flow, and response formats.

Backend contributors — The server is split into modular files:

server.js              → Entry point (wires everything together)
db/index.js            → Database connection, schema, migration
db/statements.js       → All prepared SQL statements
middleware/auth.js      → Session restore from cookie
middleware/guard.js     → Route protection + role guard
routes/auth.js         → Login, register, logout
routes/admin.js        → Admin user management + logs
routes/teacher.js      → Teacher student progress + token usage
routes/conversation.js → Conversation logging + token tracking
routes/token.js        → OpenAI ephemeral key generation
utils/ip.js            → Client IP extraction
utils/logger.js        → Access + conversation log helpers
utils/prompts.js       → System prompts

New features should go in their own route file. Import and mount in server.js with app.use(yourRoutes).

License

• iAmTeacher Frontend/app is dual-licensed under the AGPLv3 license and a bespoke license granted exclusively to Zymple. While the general public may use, modify, and distribute the software under the terms of the AGPLv3, Zymple is additionally permitted to use, modify, and distribute the software under the terms of a separate, bespoke license at Zymple's discretion.

Zymple is a business unit of Manima BKK Co., Ltd.

Special Thanks

This project is made possible by