ClassTrack (CTrack)

Hệ thống quản lý lớp học và điểm danh trực tuyến với Message Queue để high-concurrency.

Tính năng

• Quản lý lớp học: Tạo, cập nhật, xóa lớp
• Quản lý sinh viên: Thêm, xóa, xem danh sách theo lớp
• Điểm danh:
  • Tạo buổi học (session)
  • Check-in qua Queue (async)
  • Xem danh sách điểm danh/vắng
• Báo cáo: Thống kê điểm danh theo buổi học

Kiến trúc

┌──────────┐     ┌──────────┐     ┌───────────┐     ┌──────────┐     ┌──────────┐
│  Student │────▶│   API    │────▶│  RabbitMQ  │────▶│  Worker   │────▶│ PostgreSQL│
│  (PWA)   │     │ (Express) │     │   Queue   │     │          │     │          │
└──────────┘     └──────────┘     └───────────┘     └──────────┘     └──────────┘
                      │                                    │
                      │                                    ▼
                      │                             ┌──────────┐
                      └────────────────────────────▶│   DLQ    │
                                                    └──────────┘

Tech Stack

Component	Technology
Backend	Node.js 18 + Express
Database	PostgreSQL 15
Message Queue	RabbitMQ 3
Containerization	Docker + Docker Compose

Quick Start

1. Khởi động hệ thống

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

2. Truy cập

Service	URL	Credentials
API	http://localhost:3000	-
RabbitMQ Management	http://localhost:15672	guest / guest
PostgreSQL	localhost:5432	ctrack / ctrack123

3. API Endpoints

Classes

# Create class
curl -X POST http://localhost:3000/api/classes \
  -H "Content-Type: application/json" \
  -d '{"name":"Lop CNTT K1","code":"CNTT-K1"}'

# Get all classes
curl http://localhost:3000/api/classes

Students

# Add student
curl -X POST http://localhost:3000/api/students \
  -H "Content-Type: application/json" \
  -d '{"studentId":"SV001","name":"Nguyen Van A","classId":1}'

# Get students by class
curl http://localhost:3000/api/classes/1/students

Sessions

# Create session (bắt đầu điểm danh)
curl -X POST http://localhost:3000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"classId":1,"name":"Buoi 1"}'

# End session (kết thúc điểm danh)
curl -X PUT http://localhost:3000/api/sessions/1/end

Attendance

# Check-in (gửi vào Queue, trả về 202 ngay)
curl -X POST http://localhost:3000/api/attendance/checkin \
  -H "Content-Type: application/json" \
  -d '{"sessionId":1,"studentId":1}'

# Check status
curl "http://localhost:3000/api/sessions/1/status?studentId=1"

# Get attendance list
curl http://localhost:3000/api/sessions/1/attendance

# Get absent students
curl http://localhost:3000/api/sessions/1/absent

4. Load Testing

# Run load test with 1000 requests
cd backend
bash loadtest.sh 1000 100 1

# Results will show:
# - Total requests
# - Requests/sec
# - Queue processing stats
# - Final attendance count

5. Monitoring

# Health check
curl http://localhost:3000/api/health

# Queue stats
curl http://localhost:3000/api/attendance/queue/stats

Resource Limits

Cấu hình cho server 2 cores / 4GB RAM:

Service	CPU Limit	RAM Limit
PostgreSQL	0.5 core	512 MB
RabbitMQ	0.5 core	512 MB
API	0.5 core	256 MB
Worker	0.5 core	256 MB

Total: 2.0 cores / 1.5 GB (còn 2.5 GB cho OS)

Load Test Results

Metric	Value
Concurrent Requests	1000
Concurrency Level	100
Total Time	~2.2 seconds
Throughput	~454 req/sec
Avg Latency	~0.22ms
Success Rate	100%
Data Loss	0%
DLQ Messages	0

Development

# Install dependencies
cd backend
npm install

# Run tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration

# Run with coverage
npm run test:coverage

Project Structure

ClassTrack/
├── docker-compose.yml
├── README.md
├── CLAUDE.md
├── docs/
│   ├── PROJECT_STRUCTURE.md
│   ├── API_ENDPOINTS.md
│   └── LOAD_TEST_REPORT.md
├── backend/
│   ├── package.json
│   ├── Dockerfile
│   ├── src/
│   │   ├── index.js
│   │   ├── config/
│   │   ├── controllers/
│   │   ├── routes/
│   │   ├── models/
│   │   ├── services/
│   │   ├── workers/
│   │   └── utils/
│   └── tests/
│       ├── unit/
│       ├── integration/
│       └── performance/
└── assets/
    └── manifest.json

License

MIT