KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #codex #typescript #ai-agents #ai-agent #cli #claude-code #open-source #deepseek-harness #dsh-plugin #python #mcp

DoubtDesk

★ 102 Open GitHub ↗

We built an anonymous, AI-powered doubt-solving platform integrated with classrooms where students can ask questions without fear and get instant answers

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# DoubtDesk

**An AI-powered collaborative classroom platform where students get instant doubt resolution, teachers manage virtual classrooms, and analytics drive better learning outcomes.**

[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/knoxiboy/DoubtDesk/main/LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://raw.githubusercontent.com/knoxiboy/DoubtDesk/main/CONTRIBUTING.md)
[![GSSoC 2026](https://img.shields.io/badge/GSSoC-2026-orange.svg)](https://raw.githubusercontent.com/knoxiboy/DoubtDesk/main/)
[![Live Demo](https://img.shields.io/badge/Live-doubt--desk--seven.vercel.app-000?logo=vercel)](https://doubt-desk-seven.vercel.app/)

---

## Table of Contents

- [DoubtDesk](#doubtdesk)
  - [Table of Contents](#table-of-contents)
  - [Problem Statement](#problem-statement)
  - [Solution](#solution)
  - [Features](#features)
    - [AI Doubt Solver](#ai-doubt-solver)
    - [Virtual Classrooms](#virtual-classrooms)
    - [Classroom Analytics](#classroom-analytics)
    - [Moderation and Safety](#moderation-and-safety)
    - [Public Doubt Board](#public-doubt-board)
    - [User Profiles](#user-profiles)
  - [Architecture](#architecture)
  - [Tech Stack](#tech-stack)
  - [Screenshots](#screenshots)
  - [Demo Access](#demo-access)
  - [Getting Started](#getting-started)
    - [Prerequisites](#prerequisites)
    - [Installation](#installation)
    - [Environment Variables](#environment-variables)
  - [Project Structure](#project-structure)
  - [Contributing](#contributing)
    - [Quick Start for Contributors](#quick-start-for-contributors)
    - [Commit Message Format](#commit-message-format)
    - [Code Style](#code-style)
  - [Issue Labels and Difficulty Levels](#issue-labels-and-difficulty-levels)
    - [Difficulty Levels (GSSoC)](#difficulty-levels-gssoc)
    - [Category Labels](#category-labels)
  - [Roadmap](#roadmap)
    - [Near-Term (v1.1)](#near-term-v11)
    - [Mid-Term (v1.2)](#mid-term-v12)
    - [Long-Term (v2.0)](#long-term-v20)
  - [Code of Conduct](#code-of-conduct)
  - [Security](#security)
  - [License](#license)
  - [Contributors](#-contributors)
  - [Acknowledgments](#acknowledgments)

---

## Problem Statement

Students in colleges and universities face a recurring set of challenges that existing tools fail to address:

- **Doubts go unanswered.** Asking questions in large lectures is intimidating, and instructors are not available around the clock.
- **No structured Q&A channel.** WhatsApp and Telegram groups are chaotic — doubts get buried, and solutions are never archived or searchable.
- **Teachers lack visibility.** Instructors have no data on which topics students struggle with until exam results arrive, which is too late to intervene.
- **Existing platforms miss the mark.** Stack Overflow targets professional developers, not structured academics. ChatGPT lacks classroom context, anonymity, and teacher oversight.

DoubtDesk bridges this gap by combining AI-powered instant solving with real classroom structure, giving students answers in seconds and teachers insights in real time.

---

## Solution

DoubtDesk provides a virtual classroom environment where:

1. **Students ask doubts** via text or image (photo of a handwritten problem).
2. **AI instantly solves** the doubt with step-by-step, simplified, and exam-ready explanations.
3. **Community and teachers** can also answer, creating a layered support system.
4. **Analytics dashboard** surfaces weak topics, peak doubt hours, and resolution rates so teachers can act proactively.
5. **Moderation engine** keeps the platform academic and safe using AI content filtering with an escalating strike system.

---

## Features

### AI Doubt Solver
- Type a question or upload a photo — AI solves it instantly using Groq-accelerated LLMs.
- Structured output: Step-by-step breakdown, simplified explanation, and final answer.
- Interactive follow-ups: click any step to ask for further clarification.
- Full LaTeX rendering for math and science equations via KaTeX.
- Persistent chat history for continuing previous AI sessions.

### Virtual Classrooms
- Teachers create classrooms with unique invite codes.
- Students join using invite codes; recommended classrooms auto-surface by university and year.
- Three doubt channels per class: **AI Solve**, **Community Board**, **Teacher Lane**.
- Role-based views (Student vs Teacher) with distinct capabilities.
- Anonymous posting — students are assigned randomized identifiers (e.g., `Student_A7X`) to encourage participation without fear.

### Classroom Analytics
- **Topic Difficulty Heatmap** — highlights which subjects have the most doubts.
- **Resolution Pulse** — solved vs. pending ratio with circular progress visualization.
- **Peak Activity Timeline** — 24-hour bar chart showing when students are most active.
- **Personal AI Mentor** — per-student weak-topic detection after sufficient engagement.

### Moderation and Safety
- AI-powered content moderation flags abusive, off-topic, or spam content before it is posted.
- 3-strike system with escalating temporary account blocks (3 days for first block, increasing for subsequent violations).
- Full audit trail via moderation logs table for admin review.

### Privacy Model
- Doubts and replies are attributed to other users only by an anonymized, non-reversible handle (e.g. `Student_7F3Q2`) — never by the author's email or any other personal identifier.
- The real author is stored server-side for ownership, moderation, karma, and notifications, but is never serialized into any API response or client payload.
- Ownership is conveyed to clients via a server-computed `isOwnPost` flag rather than by exposing identifiers. See [docs/PRIVACY.md](docs/PRIVACY.md) for the full model and enforcement details.

### Public Doubt Board
- Open community board (no classroom required) with subject filters.
- Like, reply, and mark doubts as solved.
- Accessible to all authenticated users.

### User Profiles
- Personal dashboard showing doubts asked, replies given, and classrooms joined.
- Activity statistics including helpful votes received.

---

## Architecture

---

## Tech Stack

---

## Screenshots

> Screenshots are located in the `screenshots/` directory and will be updated as the UI evolves.

![Landing Page](https://raw.githubusercontent.com/knoxiboy/DoubtDesk/main/public/screenshots/landing.png)

![AI Solver](https://raw.githubusercontent.com/knoxiboy/DoubtDesk/main/public/screenshots/ai-solver.png)

![Classroom View](https://raw.githubusercontent.com/knoxiboy/DoubtDesk/main/public/screenshots/classroom.png)

![Analytics Dashboard](https://raw.githubusercontent.com/knoxiboy/DoubtDesk/main/public/screenshots/dashboard.png)

---

## Demo Access

A live instance of DoubtDesk is deployed at **[doubt-desk-seven.vercel.app](https://doubt-desk-seven.vercel.app/)**.

To explore the full classroom experience without setting up your own environment, use the sample classroom below after signing in:

**Steps to access:**
1. Visit the [live demo](https://doubt-desk-seven.vercel.app/).
2. Sign up or sign in using Clerk authentication.
3. Complete the onboarding flow (select your university, year, and role).
4. Navigate to **Classrooms** and click **Join Classroom**.
5. Enter the invite code `DNOIRL` to join the sample classroom.
6. Explore all features: post a doubt, use the AI solver, view the community board, and check analytics.

> **Note for contributors:** Using the demo classroom is strongly recommended before working on any issue. It provides context for how the platform works end-to-end.

---

## Getting Started

### Prerequisites

- **Node.js** 18 or higher
- **npm** (bundled with Node.js)
- **Git**
- API keys for the following services:
  - [Clerk](https://clerk.com) — Authentication
  - [Neon](https://neon.tech) — PostgreSQL database
  - [Groq](https://console.groq.com) — AI inference

### Installation

```bash
# 1. Fork the repository (click Fork on GitHub)

# 2. Clone your fork
git clone https://github.com/<your-username>/DoubtDesk.git
cd DoubtDesk

# 3. Install dependencies
npm install

# 4. Set up environment variables
cp .env.example .env
# Fill in your API keys (see Environment Variables below)

# 5. Start the development server
npm run dev
# Open http://localhost:3000
```

### Docker

Run DoubtDesk in a container using [Docker](https://www.docker.com/) and Docker Compose v2. External services (Neon, Clerk, Groq) are **not** containerized — configure them in `.env` as usual.

**Prerequisites:** Docker Desktop or Docker Engine with Compose v2.

```bash
# 1. Configure environment (required before first run)
cp .env.example .env
# Fill in Neon, Clerk, Groq, and other required keys

# 2. Apply database migrations against your Neon instance (one-time / as needed)
npx drizzle-kit migrate

# 3. Build and run the production image
docker compose build
docker compose up
# Open http://localhost:3000

# Stop containers
docker compose down
```

**Development with hot reload:**

```bash
docker compose --profile dev up app-dev
```

| Topic | Notes |
|-------|-------|
| **Required env vars** | Same as [`.env.example`](.env.example) and [`docs/SETUP.md`](docs/SETUP.md) |
| **Not containerized** | Neon PostgreSQL, Clerk, Groq, Inngest, Upstash, Resend |
| **Clerk redirects** | Use `http://localhost:3000` in Clerk dashboard and `NEXT_PUBLIC_APP_URL` |
| **Build-time vars** | `NEXT_PUBLIC_*` values are baked at image build; rebuild after changing them |
| **Migrations** | Run `npx drizzle-kit migrate` locally before first Docker run |
| **Inngest webhooks** | `/api/inngest` needs a public tunnel (e.g. ngrok) to test background jobs locally |
| **Video generation** | Remotion/ffmpeg may need extra system libraries; test natively if Docker video fails |

### Environment Variables

DoubtDesk relies on several external services (Clerk, Neon, Groq, Inngest, etc.).

For a complete breakdown of which services are strictly required versus optional, along with a setup verification checklist, please read the **[Local Environment Setup Guide](docs/SETUP.md)**.

> **Security:** Never commit your `.env` file. It is already included in `.gitignore`.

---

## Project Structure

```
DoubtDesk/
├── app/
│   ├── (auth)/              # Clerk authentication pages (sign-in, sign-up)
│   ├── api/                 # API routes
│   │   ├── doubts/          #   Doubt CRUD and like endpoints
│   │   ├── rooms/           #   Classroom creation, joining, management
│   │   ├── analytics/       #   Teacher analytics data endpoints
│   │   ├── ask-ai/          #   AI solver inference endpoint
│   │   ├── profile/         #   User profile data aggregation
│   │   └── inngest/         #   Background job webhook handler
│   ├── ask-ai/              # Standalone AI solver page
│   ├── dashboard/           # Analytics dashboard (teacher + student views)
│   ├── onboarding/          # First-time user onboarding flow
│   ├── profile/             # User profile page
│   ├── public-rooms/        # Public doubt board (no classroom required)
│   ├── rooms/               # Classroom list and individual classroom view
│   ├── layout.tsx           # Root layout (Clerk provider, global styles)
│   └── page.tsx             # Landing page
├── components/              # Reusable UI components
│   ├── ui/                  #   shadcn/ui primitives (Button, Card, Dialog, etc.)
│   ├── AskAIView.tsx        #   AI solver conversation component
│   ├── AskDoubt.tsx         #   Doubt submission modal
│   ├── DashboardLayout.tsx  #   Authenticated layout wrapper
│   ├── DoubtCard.tsx        #   Doubt display card with actions
│   └── Sidebar.tsx          #   Navigation sidebar
├── configs/
│   ├── db.tsx               # Neon database connection setup
│   └── schema.ts            # Drizzle ORM schema (all tables)
├── lib/
│   ├── moderation.ts        # AI content moderation and strike enforcement
│   ├── email.ts             # Warning and block notification email helpers
│   └── auth-utils.ts        # Authentication utility functions
├── inngest/                 # Background job definitions (Inngest functions)
├── scripts/                 # Developer utility and database migration scripts
├── screenshots/             # Application screenshots for documentation
└── middleware.tsx            # Clerk authentication and route protection middleware
```

---

## Contributing

Contributions are welcome from developers of all experience levels. Whether you are fixing a typo, improving the UI, or building a new feature, your work is valued.

**Before submitting a pull request, please read the full [Contributing Guide](CONTRIBUTING.md).**

### Quick Start for Contributors

1. **Browse open issues** on the [Issues](https://github.com/knoxiboy/DoubtDesk/issues) tab. Filter by `good-first-issue` or `beginner-friendly` labels.
2. **Comment on the issue** to indicate you are working on it.
3. **Fork and clone** the repository.
4. **Join the demo classroom** using invite code `DNOIRL` to understand the product before writing code.
5. **Create a branch** following the naming convention:
   - `feature/add-dark-mode-toggle`
   - `fix/classroom-invite-validation`
   - `docs/update-readme-screenshots`
6. **Make focused changes** with clear, conventional commit messages.
7. **Test locally** using `npm run dev`.
8. **Submit a PR** against the `main` branch.

### Commit Message Format

Follow the [Conventional Commits](https://www.conventionalcommits.org/) standard:

```
feat: add loading skeleton to AI solver
fix: handle empty classroom state gracefully
docs: add screenshots to README
style: improve mobile responsiveness of classroom cards
refactor: extract doubt card into reusable component
```

### Code Style

- Use TypeScript with proper interfaces — avoid `any` types.
- Follow the existing component structure in `/components` and `/app`.
- Use Tailwind CSS for styling, matching the existing dark theme (slate-950 backgrounds, blue-500/600 accents, glassmorphism patterns).
- Keep components focused: one file, one responsibility.

---

## Issue Labels and Difficulty Levels

### Difficulty Levels (GSSoC)

### Category Labels

---

## Roadmap

The following is a prioritized list of planned enhancements. Contributions toward any of these are welcome.

### Near-Term (v1.1)

### Mid-Term (v1.2)

### Long-Term (v2.0)

---

## Code of Conduct

We are committed to providing a welcoming and harassment-free experience for everyone. Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.

**In short:** Be respectful, be constructive, be kind.

---

## Security

If you discover a security vulnerability, please follow the responsible disclosure process described in [SECURITY.md](SECURITY.md).

---

## License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

---

## 👥 Contributors

We appreciate all contributors who helped improve this project ❤️

---

## Acknowledgments

- [Groq](https://groq.com) for ultra-fast AI inference
- [Clerk](https://clerk.com) for seamless authentication
- [Neon](https://neon.tech) for serverless PostgreSQL
- [shadcn/ui](https://ui.shadcn.com) for accessible UI components
- [GirlScript Summer of Code](https://gssoc.girlscript.tech/) for fostering open-source contributions

---

<p align="center">
  Built for students and teachers everywhere.
</p>

DoubtDesk

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README