Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ddthien-coder/hskdolien


https://github.com/ddthien-coder/hskdolien

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

          
# HSK Dolien - Chinese Proficiency Exam System



A comprehensive HSK (Hanyu Shuiping Kaoshi) examination platform built with Next.js 15, TypeScript, PostgreSQL, and Redis.



## Features



- 🔐 **Authentication & Security**: JWT + Refresh tokens, RBAC (5 roles), rate limiting

- 📚 **Question Bank**: Multi-language support (zh-CN, zh-TW, pinyin, Vietnamese), 7 question types

- 🎯 **Exam Generation**: Manual creation + intelligent auto-generation with balancing algorithm

- ✍️ **Exam Taking**: Real-time autosave, progress tracking, resume capability

- 🤖 **Auto-Grading**: Fuzzy matching for fill-in-blank, exact match for MCQ, partial credit system

- 👨‍🏫 **Manual Grading**: Queue management for essays, rubric-based scoring

- 🛡️ **Anti-Cheating**: Proctor sessions, violation tracking, suspicious activity detection

- 📈 **Analytics**: Performance tracking, skill breakdown, system-wide reporting with Recharts

- 🎓 **Certificates**: Auto-generated HTML certificates for passed exams

- 📋 **Exam Templates**: Reusable exam configurations for quick exam creation

- 💾 **Media Library & Document Storage**: Centralized file management with upload, download, and organization for images, audio, and documents (PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, CSV)

- ⚡ **Job Queue**: Background processing for grading, certificates, and cleanup tasks

- 👤 **Admin Panel**: Complete management UI for users, exams, question banks, and system monitoring



## Tech Stack



- **Framework**: Next.js 16.0.1 (App Router)

- **Language**: TypeScript 5 (strict mode, zero `any` types)

- **Database**: PostgreSQL 17 with Prisma ORM

- **Cache**: Redis 7

- **Authentication**: JWT with httpOnly cookies

- **Validation**: Zod v4

- **Charts**: Recharts 3

- **Styling**: Tailwind CSS 4

- **Deployment**: Docker + PM2 cluster mode



## Getting Started



### Prerequisites



- Node.js 20+

- PostgreSQL 17

- Redis 7



### Installation



```bash

# Install dependencies

npm install



# Set up environment variables

cp .env.example .env

# Edit .env with your database and Redis credentials



# Generate Prisma client

npm run db:generate



# Push schema to database

npm run db:push



# Seed demo data

npm run db:seed

```



### Development



```bash

npm run dev

```



Open [http://localhost:3000](http://localhost:3000)



### Demo Accounts



- **Admin**: admin@hsk.com / Admin123!

- **Teacher**: teacher@hsk.com / Teacher123!

- **Candidate**: candidate@hsk.com / Candidate123!



## Docker Deployment



```bash

# Build and run with Docker Compose

docker-compose up -d



# View logs

docker-compose logs -f app



# Stop services

docker-compose down

```



## PM2 Deployment



```bash

# Build for production

npm run build



# Start with PM2

pm2 start ecosystem.config.js



# Monitor

pm2 monit

```



## API Endpoints



### Authentication

- `POST /api/auth/register` - Register new user

- `POST /api/auth/login` - Login

- `POST /api/auth/logout` - Logout

- `POST /api/auth/refresh` - Refresh access token

- `GET /api/auth/me` - Get current user



### Question Banks

- `GET /api/banks` - List banks

- `POST /api/banks` - Create bank

- `GET /api/banks/[id]` - Get bank details

- `PATCH /api/banks/[id]` - Update bank

- `DELETE /api/banks/[id]` - Delete bank



### Questions

- `GET /api/questions` - List questions

- `POST /api/questions` - Create question

- `PATCH /api/questions/[id]` - Update question

- `DELETE /api/questions/[id]` - Delete question



### Exams

- `GET /api/exams` - List exams

- `POST /api/exams` - Create exam

- `POST /api/exams/generate` - Auto-generate exam

- `GET /api/exams/[id]` - Get exam details

- `POST /api/exams/[id]/publish` - Publish exam

- `POST /api/exams/[id]/questions` - Add questions



### Attempts

- `GET /api/attempts` - List user attempts

- `POST /api/attempts` - Start attempt

- `POST /api/attempts/[id]/answer` - Save answer (autosave)

- `POST /api/attempts/[id]/submit` - Submit attempt

- `POST /api/attempts/[id]/grade` - Auto-grade attempt



### Grading

- `GET /api/grading/manual` - Get manual grading queue

- `POST /api/grading/manual` - Submit manual grade



### Proctor

- `POST /api/proctor/[attemptId]` - Initialize session

- `POST /api/proctor/[attemptId]/flag` - Record violation

- `GET /api/proctor/[attemptId]/analysis` - Analyze suspicious activity



### Analytics

- `GET /api/analytics/user` - User performance

- `GET /api/analytics/exam/[id]` - Exam statistics

- `GET /api/analytics/system` - System-wide analytics



### Admin

- `GET /api/admin/dashboard` - Admin dashboard data

- `GET /api/admin/users` - List users

- `PATCH /api/admin/users/[id]` - Update user

- `DELETE /api/admin/users/[id]` - Delete user

- `GET /api/admin/exams` - List all exams

- `PATCH /api/admin/exams/[id]` - Update exam

- `DELETE /api/admin/exams/[id]` - Delete exam

- `GET /api/admin/banks` - List all banks

- `DELETE /api/admin/banks/[id]` - Delete bank

- `POST /api/admin/banks/[id]/transfer` - Transfer ownership

- `GET /api/admin/activity` - Activity logs



### Templates

- `GET /api/templates` - List exam templates

- `POST /api/templates` - Create template

- `GET /api/templates/[id]` - Get template details

- `PATCH /api/templates/[id]` - Update template

- `DELETE /api/templates/[id]` - Delete template



### Media & Document Storage

- `GET /api/media` - List all media files (with filtering and search)

- `POST /api/upload` - Upload file (image, audio, document)

- `GET /api/media/[id]` - Get media details

- `PATCH /api/media/[id]` - Update media metadata (description, tags)

- `DELETE /api/media/[id]` - Delete media file

- `POST /api/media/bulk` - Bulk delete media files



### Certificates

- `GET /api/certificates/[attemptId]` - Generate certificate HTML



### Job Queue

- `GET /api/jobs` - List jobs (admin only)

- `POST /api/jobs` - Create job

- `GET /api/jobs/[id]` - Get job status



## Database Schema



14 models: User, RefreshToken, PasswordReset, Bank, Question, QuestionTranslation, ExamTemplate, Exam, ExamQuestion, Attempt, Answer, GradeRecord, ProctorSession, AuditLog, JobQueue



## Scripts



```bash

npm run dev          # Start development server

npm run build        # Build for production

npm run start        # Start production server

npm run lint         # Run ESLint

npm run db:generate  # Generate Prisma client

npm run db:push      # Push schema to database

npm run db:migrate   # Run migrations

npm run db:seed      # Seed demo data

npm run db:studio    # Open Prisma Studio

```



## Background Worker



Run the background job processor for auto-grading, certificate generation, and cleanup:



```bash

# Development

ts-node scripts/worker.ts



# Production (with PM2)

pm2 start scripts/worker.ts --name hsk-worker --interpreter ts-node

```



## Admin Panel



Access the admin panel at [http://localhost:3000/admin](http://localhost:3000/admin)



Features:

- Dashboard with real-time metrics

- User management (roles, activation)

- Exam management (publish/unpublish)

- Question bank management

- **Media library & document storage** (upload, download, organize files)

- Activity audit logs

- System health monitoring



### Question Type Distribution System:

    The distribution system supports all 6 HSK question types:

    MCQ - Multiple Choice Questions

    FILL_BLANK - Fill in the Blank

    LISTENING - Listening Comprehension

    WRITING - Written Essays

    MATCHING - Match Items

    DICTATION - Listen and Write



## License



MIT