StudyWise

🌐 English | 简体中文

AI-powered learning annotation assistant — Chat with AI to generate study content, annotate any text, get instant AI answers, and review with auto-generated summaries and quizzes.

🇨🇳 中文简介：StudyWise 是一款 AI 学习批注助手。与 AI 对话生成学习内容，选中文字添加笔记/问题，AI 即时结合上下文解答，学完自动生成总结与复习题，并支持导出离线 HTML。数据全部本地存储（SQLite），自带 API Key 即可使用。完整中文文档见 README.zh-CN.md。

🚀 Ready for your next learning session.

---

📸 Screenshots

⚠️ Placeholder — run npm run dev, take screenshots, and drop them into docs/screenshots/. Then update the image paths below.

Main learning interface	Annotations & AI replies	Summary & review quiz

---

✨ Features

• 💬 AI generates study content — tell AI what you want to learn, and it produces structured HTML learning material in a single conversation.
• 📝 Select-and-annotate — highlight any text in the content to add a note or ask a question; notes (green) and questions (yellow) are visually distinct.
• 🤖 Instant AI replies — AI answers your questions with the surrounding content as context.
• 🔗 Two-way scrolling sync — click a highlight and the annotation panel scrolls to it (and vice versa); scrolling one panel auto-scrolls the other.
• 🔎 Multi-turn follow-ups — keep asking follow-up questions on any AI answer; the thread auto-collapses to the first reply.
• 📊 AI summary — after learning, AI generates a knowledge summary based on your notes and questions.
• ❓ Review quizzes — auto-generated fill-in-the-blank / Q&A review questions with interactive answering.
• 📤 Export standalone HTML — export content + annotations + summary + quiz into a single offline-readable HTML file.
• 🌐 Multiple AI providers — switchable providers (Volcengine DeepSeek / OpenAI-compatible / Claude) in one click.
• 💾 Local-first data — everything is stored in local SQLite; your API key stays yours.

---

🚀 Quick Start

Prerequisites

• Node.js 20+ (CI runs on Node 24; developed and tested on Node 20/24)
• npm (bundled with Node)
• An API key from an OpenAI-compatible AI provider (Volcengine Ark recommended)

1. Clone the repo

git clone https://github.com/free1101/studywise.git
cd studywise

2. Install dependencies

npm install

3. Configure environment variables

Copy .env.example to .env.local and fill in your API key:

cp .env.example .env.local

Variable	Description	How to get
VOLCENGINE_API_KEY	Volcengine Ark API key	Volcengine Ark console
VOLCENGINE_ENDPOINT	API endpoint (pre-filled)	Leave as-is
VOLCENGINE_MODEL	Model name (pre-filled)	Leave as-is
OPENAI_API_KEY	OpenAI (or any OpenAI-compatible endpoint) API key	OpenAI platform
OPENAI_BASE_URL	OpenAI-compatible endpoint URL (pre-filled)	Leave as-is
OPENAI_MODEL	Model name (pre-filled)	Leave as-is
CLAUDE_API_KEY	Anthropic Claude API key (ANTHROPIC_API_KEY also works)	Anthropic console
CLAUDE_BASE_URL	Anthropic OpenAI-compatible endpoint (pre-filled)	Leave as-is
CLAUDE_MODEL	Claude model name (pre-filled)	Leave as-is
DEFAULT_AI_PROVIDER	Default provider: volcengine / openai / claude	Default volcengine

Three providers, one click — switch via DEFAULT_AI_PROVIDER or the in-app status bar:

• volcengine — Volcengine Ark (DeepSeek, recommended for CN users)
• openai — OpenAI official or any OpenAI-compatible endpoint (DeepSeek official, Qwen, Kimi, GLM, Ollama, etc. — just point OPENAI_BASE_URL at it)
• claude — Anthropic Claude via the official OpenAI-compatible endpoint

4. Start the dev server

npm run dev

Open http://localhost:3000 and start learning.

---

🧱 Tech Stack

Layer	Choice
Framework	Next.js 16 (App Router)
Language	TypeScript (strict mode)
UI	TailwindCSS + shadcn/ui
AI	Volcengine DeepSeek (OpenAI-compatible)
Database	SQLite + better-sqlite3
ORM	Drizzle ORM
Annotation	@recogito/react-text-annotator

📁 Project Structure

studywise/
├── app/
│   ├── page.tsx                    # Main learning UI (three-pane layout)
│   ├── layout.tsx                  # Global layout
│   └── api/
│       ├── chat/route.ts           # AI conversation (streaming)
│       ├── contents/route.ts       # Save content
│       ├── annotations/            # Annotation CRUD
│       │   ├── route.ts
│       │   └── [id]/route.ts
│       ├── ai/
│       │   ├── reply/route.ts      # AI reply to annotation (multi-turn)
│       │   └── summarize/route.ts  # AI summary + review questions
│       ├── summaries/route.ts      # Persisted summary retrieval
│       └── export/route.ts         # Export standalone HTML
├── components/
│   ├── ui/                         # shadcn/ui base components
│   ├── chat/                       # Chat panel & message
│   ├── content/                    # Content viewer + annotation popup
│   ├── annotation/                 # Annotation list & detail
│   ├── summary/                    # Summary + review quiz
│   ├── export/                     # Export dialog
│   └── layout/                     # Sidebar, resizable panel, status bar
├── hooks/
│   ├── useAnnotations.ts           # Annotation CRUD hook
│   └── useChat.ts                  # AI chat hook
├── lib/
│   ├── db.ts                       # Drizzle + SQLite connection
│   ├── schema.ts                   # DB schema & types
│   └── ai/
│       ├── providers.ts            # Unified AI provider interface
│       └── volcengine.ts           # Volcengine DeepSeek wrapper
├── scripts/                        # Regression test scripts
├── docs/screenshots/               # Place screenshots here
├── AGENTS.md                       # Dev conventions
├── LICENSE
└── package.json

---

🔧 How It Works

1. Conversation → Content — you chat with AI; when AI produces HTML learning material, the front-end extracts and renders it into the central content viewer.
2. Annotate → Reply — selecting text opens a popup to add a note/question; the annotation is stored in SQLite and AI replies with the surrounding content as context. Follow-up questions reuse the same endpoint with the previous reply for multi-turn coherence.
3. Scroll Sync — highlights and annotation cards share stable IDs; scrolling either panel reports the visible annotation and syncs the other side (with programmatic-scroll guards to prevent loops).
4. Summarize & Export — on completion, AI summarizes your notes/questions into a summary plus review questions (persisted to DB); the export endpoint merges content, annotations, summary, and quiz into one standalone HTML file.

---

📚 Docs

• AGENTS.md — development conventions, coding standards, and the self-check checklist.
• question.txt — an audit trail of bug reports, root-cause analysis, and fixes across multiple iterations (evidence of quality and rigor).
• scripts/ — regression tests:
  • node scripts/api-test.mjs — API regression tests across all backend routes (needs the dev server running).
  • node scripts/frontend-logic-test.mjs — dependency-free front-end logic contract tests (HTML extraction).

---

❓ FAQ

How do I switch AI providers? Set DEFAULT_AI_PROVIDER in .env.local to volcengine, openai, or claude, configure the matching API key, and (optionally) select the provider from the in-app status bar. Any OpenAI-compatible endpoint works with the openai provider.

Where is my data stored? Locally in a SQLite database file (local.db) at the project root. Nothing leaves your machine except the AI API requests you make.

How do I deploy this? It's a standard Next.js app — build with npm run build, then npm run start (or deploy to Vercel). Just make sure the SQLite file path is writable in your deployment environment and that your API key is set.

---

🤝 Contributing

Contributions are welcome! Please:

1. Read AGENTS.md to follow the conventions.
2. Fork the repo and create a feature branch.
3. Ensure npm run lint and npm run build pass, and run the regression tests in scripts/.
4. Open a pull request describing the change.

---

⭐ Support

If you find StudyWise useful, please give it a star ⭐ — it helps more people discover the project and keeps the motivation going!

---

📄 License

This project is licensed under the MIT License.

---

⚠️ Disclaimer

• Local data only — all learning content, annotations, and summaries are stored locally in SQLite. We never upload your data to any server.
• Bring your own API key — StudyWise calls AI providers using your API key. You are responsible for the usage and cost of your own key.
• This is an open-source learning demo project; use at your own discretion.