LexiForm

Turn any text into an interactive quiz. Paste content or enter a topic, and LexiForm generates multiple choice, true/false, fill-in-the-blank, and matching questions instantly.

Quick Start

# Backend
cd backend && npm install && npm run dev

# Frontend (separate terminal)
cd frontend && npm install && npm run dev

Backend runs on http://localhost:3000, frontend on http://localhost:3001.

What It Does

• Generate quizzes from pasted text (up to 2,000 characters)
• Generate quizzes from topic keywords using Google Gemini AI
• Upload PDFs and extract questions automatically
• Adaptive difficulty that adjusts based on performance
• SM-2 spaced repetition flashcards
• Shareable quiz links with leaderboards
• User accounts with progress tracking

Stack

Backend: Express + TypeScript + SQLite (better-sqlite3), Google Gemini integration, JWT auth

Frontend: Next.js 16 + React 19 + Tailwind CSS + Zustand, Radix UI components

Project Structure

lexiform/
├── backend/           # Express API server
│   ├── src/
│   │   ├── routes/    # API endpoints
│   │   ├── lib/       # DB, auth, adaptive, Gemini
│   │   └── tests/     # Jest tests
│   └── openapi.yaml   # Full API spec
└── frontend/          # Next.js app
    └── src/
        ├── app/       # Pages
        ├── components/
        └── store/     # Zustand state

Development

Requirements

• Node.js 20+
• npm 9+

Backend Setup

cd backend
cp .env.example .env
npm install
npm run dev

Generate a JWT secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Copy the output into .env as JWT_SECRET.

Frontend Setup

cd frontend
npm install
npm run dev

Running Tests

# Backend (Jest)
cd backend && npm test

# Frontend (Vitest)
cd frontend && npm test

# Frontend E2E (Playwright)
cd frontend && npm run e2e

Environment Variables

Backend requires these (see backend/.env.example):

Variable	Default	Purpose
PORT	3000	Server port
JWT_SECRET	Required	Auth token signing
GEMINI_API_KEY	Optional	AI quiz generation
USE_PERSISTENCE	true	SQLite storage
DB_PATH	./data/lexiform.sqlite	Database file

Full list in backend/.env.example.

API Endpoints

Key endpoints (all under /api):

• POST /generate-quiz - Generate quiz from text
• POST /generate-quiz-from-topic - AI-generated quiz from topic
• POST /quiz/upload-pdf - Upload PDF, extract questions
• POST /quiz/submit - Submit answers, get score
• GET /quiz/:id - Retrieve stored quiz
• POST /auth/register - Create account
• POST /auth/login - Login
• GET /flashcards - List flashcards
• POST /flashcards/:id/review - SM-2 review
• GET /leaderboard/:quizId - Quiz leaderboard

Full spec: backend/openapi.yaml (740 lines, OpenAPI 3.0.3).

Deployment

Backend ships with a Dockerfile:

cd backend
docker build -t lexiform-backend .
docker run -p 3000:3000 -e JWT_SECRET=your-secret lexiform-backend

Frontend builds to static files:

cd frontend
npm run build
npm run start  # or deploy .next/ to Vercel

CI runs on GitHub Actions (.github/workflows/ci.yml): lint, typecheck, test, build.

Contributing

See CONTRIBUTING.md for workflow, code style, and PR process.

Architecture

See docs/ARCHITECTURE.md for system design, data flow, and integration points.

License

MIT