CodeTutor

English | 简体中文

📖 Featured post (Chinese): Turning scattered tutorials into AI coaching plans — CodeTutor tech deep-dive on Juejin (Frontend)

CodeTutor is an AI coding tutor for Chinese-speaking learners. It turns scattered tutorials, videos, code snippets, and learning materials into guided learning paths with AI coaching, progress tracking, feedback loops, achievements, and admin operations.

The repository is a full-stack MVP built with Next.js App Router, Supabase, TypeScript, and an extensible AI provider layer. It includes the learner workspace, admin console, API route handlers, service modules, Supabase migrations, and product/architecture planning documents.

Screenshots

AI Learning Chat	Learning Map	Achievements
Streaming AI · multimodal · TTS	Visual progress tracking	Daily check-in · badges · credits

Material Intake	Admin Console	Landing Page
Paste a link → AI generates a learning plan	Users, learning, AI, finance dashboards	Responsive landing & onboarding flow

💡 Place screenshots in public/screenshots/. Recommended: 1280×720, PNG or WebP.

Why CodeTutor

The problem: the last mile of learning to code

The Chinese internet has no shortage of tutorials—Bilibili, Juejin, Zhihu, MOOCs. But there's a huge gap between "I watched it" and "I can do it":

• 📚 Bookmarked 100 tutorials, finished fewer than 3
• 🎯 No idea what to learn next at your current skill level
• 🤷 Stuck with no one to ask, and Google doesn't understand your context
• 📉 Learn-and-forget loop—no tracking, no feedback, no sense of progress

The solution: not just another video platform

CodeTutor doesn't create tutorials. It turns existing tutorials into executable AI coaching plans:

1. Paste any tutorial link → AI parses the content and generates a leveled learning plan
2. AI coach in real time → streaming chat, follow-up questions, code review, next-task breakdown
3. Visible progress → learning map, daily check-ins, achievement badges, credit system
4. Self-hostable & extensible → AGPL-3.0 open source, Supabase + Next.js, swappable AI providers

Who is this for

Role	Use case
🧑‍💻 Programming learners	Turn scattered tutorials into AI-coached learning with feedback and tracking
👨‍🏫 Educators / bootcamps	Self-host a student management system with AI-assisted teaching
🏗️ Developers	Study a production-grade Next.js 16 full-stack architecture and AI provider design
🔬 Researchers	Build on top for learning behavior analytics and AI teaching effectiveness studies

Current Status

CodeTutor is a partially implemented full-stack MVP, not a polished turnkey distribution yet.

Implemented areas include:

• Phone-first authentication, WeChat/Douyin identity linking, homepage session recovery, onboarding, profile, avatar upload, and feedback.
• Learner workspace with AI learning chat, streaming responses, image/voice attachments, text-to-speech playback, task completion, daily check-in, achievements, history, and orders.
• Self-directed tutorial-link intake with async material planning, multimodal evidence extraction, quality gates, editable drafts, and transactional confirmation.
• Admin console for dashboard, users, learning paths/templates, AI provider/model/agent/media settings, site information, help center, changelog, notifications, system settings, finance, and feedback.
• WeChat Native and Alipay scan payment configuration, subscription entitlement activation, order management, notification settings, analytics ingestion, and OpenAPI documentation.
• Supabase migrations through 057.

Still planned or partial:

• Finer-grained admin permissions.
• Internal notes, manual score adjustment, refunds, auto-renewal, JSAPI/H5 payment variants, finance export, invoices, and deeper reconciliation.
• Later AI orchestration operations such as prompt versioning, rollout controls, richer cost/stability dashboards, and shared queue infrastructure.

Tech Stack

Layer	Technology
App framework	Next.js 16.2 App Router
UI runtime	React 19.2
Language	TypeScript 5.7
Styling	Tailwind CSS 4.2, shadcn/ui-style primitives
Data validation	Zod, zod-to-openapi
Backend	Next.js route handlers plus server/modules services
Database	Supabase PostgreSQL
Storage	Supabase Storage
AI layer	Provider/agent/skill abstractions under ai/ and server/modules
Package manager	pnpm
Node.js	22.18.0 recommended

Repository Layout

app/                     Next.js App Router pages and API routes
app/api/                 BFF/API route handlers
ai/                      AI provider, agent, and skill orchestration helpers
components/              Shared layout and UI primitives
constants/               Cross-feature constants
docs/plans/              PRD, architecture, API, schema, and roadmap documents
features/                Feature pages, components, static data, and view models
hooks/                   Shared React hooks
lib/                     API clients, helpers, and Supabase clients
providers/               React context providers
public/                  Static assets
scripts/                 Targeted verification scripts
server/lib/              Server-side shared utilities
server/modules/          Domain services
supabase/migrations/     Database migrations
types/                   Shared TypeScript types

Core conventions:

• app/ stays thin. Page logic should live under features/.
• Components used by one domain belong in features/<domain>/components; shared components belong in components/.
• API contract changes should be reflected in server/modules/api-docs/openapi.ts and server/modules/api-docs/schemas.ts.
• Database or environment changes should update migrations, .env.example, and the relevant planning docs.

Quick Start

Requirements

• Node.js 22.18.0
• pnpm
• A Supabase project, local or remote

Install

pnpm install
cp .env.example .env.local

Fill the required Supabase and provider variables in .env.local. Do not commit real secrets.

pnpm dev

Open http://localhost:3000. The admin console lives under /admin and requires an admin account.

Database

The schema is tracked in supabase/migrations/ and currently runs through migration 057.

Option A: Remote Supabase project (recommended for quick start)

1. Create a free project at supabase.com

2. Get your project URL and anon/service-role keys from Settings > API

3. Fill NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, and SUPABASE_SERVICE_ROLE_KEY in .env.local

4. Apply migrations using the Supabase Dashboard SQL editor or the helper script:

   pnpm db:run:file supabase/migrations/001_init.sql
   # Repeat for 002 through 057, or concatenate and apply at once

5. Verify connectivity:

   pnpm db:check

Option B: Local Supabase (via Supabase CLI)

1. Install the Supabase CLI

2. Start the local stack:

   supabase init   # first time only
   supabase start

3. Copy the local project URL and keys from the CLI output to .env.local

4. Apply all checked-in migrations:

   # Supabase CLI picks up migrations from supabase/migrations/
   supabase db push
   # Or use the helper scripts with your local DATABASE_* variables:
   pnpm db:check

A one-command local Supabase bootstrap is not yet part of the public developer experience. Contributions to improve the local setup story are welcome.

Useful Scripts

pnpm dev
pnpm build
pnpm start
pnpm lint
pnpm test:openapi-document
pnpm test:admin-users
pnpm test:admin-learning
pnpm test:admin-ai
pnpm test:admin-site
pnpm test:admin-settings
pnpm test:payment
pnpm test:workspace-sidebar
pnpm test:workspace-shell-collapse

The project also has many targeted scripts under scripts/. Prefer the smallest script that covers the area you changed.

Documentation

Start with:

• docs/plans/README.md
• Product requirements
• Technical architecture
• API spec
• Database schema design
• AI orchestration design
• Admin console design

When code and documentation disagree, treat code and migrations as the source of truth, then update the docs.

Contributing

Contributions are welcome. Good first areas include documentation, local setup improvements, targeted test scripts, UI polish, issue reproduction, and small service-level fixes.

Before opening a pull request:

1. Read CONTRIBUTING.md.
2. Keep the change narrowly scoped.
3. Run the smallest relevant verification command.
4. Never include secrets, production credentials, user data, or private operational notes.

By contributing, you agree that your contribution is licensed under AGPL-3.0-only.

Security

Please do not report vulnerabilities through public issues. See SECURITY.md for the private reporting process and secret-handling expectations.

License

CodeTutor is licensed under the GNU Affero General Public License v3.0 only.

Copyright (C) 2026 Shanghai Zhiku Shuneng Technology Co., Ltd. (上海智酷数能科技有限公司).

SPDX identifier:

AGPL-3.0-only

You may use, modify, self-host, and provide commercial services with this software. If you modify CodeTutor and make it available to users over a network, you must provide those users access to the corresponding source code under AGPL-3.0.

See LICENSE for the full license text.

Trademark and Branding

The CodeTutor name, logo, the domain www.codetutor.cn, and all official service branding are proprietary to Shanghai Zhiku Shuneng Technology Co., Ltd.（上海智酷数能科技有限公司） and are not licensed under AGPL-3.0. Forks and self-hosted deployments may not imply they are the official CodeTutor service, and may not use the CodeTutor name or branding in ways that suggest endorsement or affiliation, unless they have explicit written permission.

Production credentials, private user data, hosted-service data, and private infrastructure configuration are not part of the open-source release.