AI 기반 교육 플랫폼을 위한 마이크로서비스 아키텍처 백엔드 시스템입니다.
┌───────────────────────────────────────────────────────────────┐
│ Client (Frontend) │
└───────────────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────┐
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │Auth Service │ │ Market │ │
│ │ (Port │ │ Service │ │
│ │ 8003) │ │ (Port 8005) │ │
│ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │
│ │ JWT 인증 │ 포인트/구매 │
│ ▼ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Content Generation Services │ │
│ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │
│ │ │ Math │ │Korean│ │ Eng │ │ │
│ │ │ 8001 │ │ 8004 │ │ 8002 │ │ │
│ │ └───┬──┘ └───┬──┘ └───┬──┘ │ │
│ └──────┼─────────┼─────────┼───────────┘ │
│ └─────────┼─────────┘ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ Notification │ │
│ │ Service (8006) │ │
│ │ (SSE Real-time) │ │
│ └────────────────────┘ │
└────────────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ PostgreSQL │◄───┤ Celery/Redis │───►│ Redis │
│ (Port 5433) │ │ Task Queue │ │ (Port 6379) │
│ │ │ │ │ │
│ 서비스별 스키마 │ │ • Math │ │ • Task Queue │
│ 독립 관리 │ │ • Korean │ │ • Result │
│ │ │ • English │ │ Backend │
└──────────────┘ └──────────────┘ └──────────────┘
[데이터 흐름]
1. 사용자 요청 → Auth Service (JWT 발급/검증)
2. 인증된 요청 → Content Services (Math/Korean/English)
3. 콘텐츠 생성 → Celery Task Queue (비동기)
4. Worker → Gemini/GPT API 호출 → AI Judge 검증
5. 완료 시 → Notification Service (SSE) → 사용자 실시간 알림
6. 마켓 거래 → Market Service → PostgreSQL 트랜잭션 보장
- 마이크로서비스 기반: 독립적으로 배포 가능한 6개 서비스
- 중앙 인증: Auth Service를 통한 JWT 토큰 검증
- 비동기 처리: Celery + Redis를 활용한 백그라운드 작업
- AI 통합: Gemini 2.5 Pro, GPT-4o-mini 기반 문제 생성 및 검증
- 서비스 간 통신: HTTP REST API
- 데이터 격리: 서비스별 PostgreSQL 스키마 분리
- 확장성: Docker Compose 기반 컨테이너 오케스트레이션
인증 및 사용자 관리
-
핵심 기능:
- 교사/학생 회원가입 및 로그인 (JWT)
- 클래스룸 생성 및 학생 가입 관리
- 교사-학생 간 쪽지 시스템
- 중앙 토큰 검증 (
/api/auth/verify-token)
-
주요 플로우:
- 교사가 클래스 생성 → 고유 클래스 코드 발급
- 학생이 클래스 코드로 가입 신청 → 교사 승인/거부
- 승인된 학생과 교사 간 쪽지 송수신
-
데이터 모델: Teacher, Student, ClassRoom, StudentJoinRequest, Message
-
기술: FastAPI, PostgreSQL, JWT, bcrypt, Redis
AI 기반 수학 문제 생성 및 채점
-
핵심 기능:
- 교육과정 기반 문제 자동 생성 (Gemini 2.5 Pro)
- AI Judge 검증 시스템 (GPT-4o-mini)
- TikZ 그래프 자동 생성 (LaTeX)
- OCR 기반 서술형 채점 (Google Vision API)
- 난이도 3단계 (A: 직접계산, B: 응용번역, C: 통합발견)
-
주요 플로우:
- 교사가 학년/단원/난이도 설정 → 문제 생성 요청
- Celery 백그라운드에서 Gemini로 문제 생성
- AI Judge가 수학정확성/정답일치/완결성/논리성 검증
- 불합격 문제는 피드백 포함 재생성 (최대 3회)
- 학생 답안 제출 → OCR 인식 → AI 채점 → 피드백 제공
-
데이터 모델: Worksheet, Problem, GradingSession, Curriculum
-
기술: FastAPI, Celery, Gemini, GPT-4o-mini, Google Vision API
AI 기반 국어 문제 생성 및 채점
-
핵심 기능:
- 지문 기반 문제 생성 (시/소설/수필/문법)
- AI Judge 유형별 검증 (문학성, 서사성, 논증성)
- 병렬 처리 (ThreadPoolExecutor)
- 과제 생성 및 배포
-
주요 플로우:
- 교사가 국어 유형/난이도 설정 → 문제 생성 요청
- data/ 폴더에서 지문 랜덤 선택 (poem/novel/non-fiction/grammar)
- ThreadPoolExecutor로 작품별 병렬 생성
- AI Judge가 유형별 기준 검증 (각 항목 ≥ 3.5/5.0)
- 불합격 문제 재생성 → DB 저장
- 과제 배포 → 학생 제출 → 채점
-
데이터 모델: Worksheet, Problem, GradingSession, Assignment
-
기술: FastAPI, Celery, Gemini, GPT-4o-mini, ThreadPoolExecutor
워크시트 마켓플레이스
-
핵심 기능:
- 워크시트 상품 등록 및 판매
- 포인트 시스템 (충전/구매/수익)
- 자동 가격 책정 (10문제: 1,500P, 20문제: 3,000P)
- 리뷰 시스템 (추천/보통/비추천)
-
주요 플로우:
- 교사가 워크시트 등록 → 자동 가격 책정 및 태그 생성
- 다른 교사가 포인트로 구매
- 구매자 포인트 차감 → 판매자 수익 적립 (플랫폼 수수료 10%)
- 워크시트 자동 복사 → 구매자 계정에 추가
- 구매자 리뷰 작성 → 만족도 계산
-
데이터 모델: MarketProduct, MarketPurchase, MarketReview, UserPoint
-
기술: FastAPI, PostgreSQL, Auth Service 미들웨어
영어 문제 생성 및 관리 (담당자: 다른 개발자)
-
핵심 기능: (추가 예정)
- AI 기반 영어 문제 생성
- 영어 워크시트 관리
- 영어 채점 시스템
-
포트: 8002
-
기술 스택: FastAPI, PostgreSQL, AI Models
실시간 알림 및 WebSocket (담당자: 다른 개발자)
-
핵심 기능: (추가 예정)
- WebSocket 기반 실시간 알림
- 메시지 푸시 알림
- 이벤트 브로드캐스팅
-
포트: 8006
-
기술 스택: FastAPI, Redis, WebSocket
- FastAPI: 고성능 비동기 웹 프레임워크
- SQLAlchemy: ORM (PostgreSQL)
- Pydantic: 데이터 검증
- PostgreSQL 15: 메인 데이터베이스
- Redis 7: 캐싱 및 Celery 브로커
- Gemini 2.5 Pro: 문제 생성
- GPT-4o-mini: AI Judge 검증
- Google Vision API: OCR (수학 서술형)
- Celery: 비동기 작업 처리
- Redis: 메시지 브로커
- JWT (HS256): 토큰 기반 인증
- bcrypt: 비밀번호 해싱
- Docker: 컨테이너화
- Docker Compose: 오케스트레이션
┌─────────────────────────────────────────────────────────────────┐
│ [1] 사용자 요청 접수 │
│ POST /api/worksheets/generate │
│ {grade, unit, difficulty_ratio, problem_count, ...} │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ [2] Celery 비동기 태스크 생성 │
│ • FastAPI → Celery.delay() → Task ID 즉시 반환 │
│ • 사용자 체감 응답 시간: 3초 이내 (202 Accepted) │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ [3] Celery Worker - 백그라운드 처리 시작 │
│ • 교육과정 데이터 로드 (curriculum.json) │
│ • 프롬프트 구성 (난이도/유형 분배) │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ [4] AI 문제 생성 (Gemini 2.5 Pro) │
│ │
│ Math Service: │
│ • TikZ 그래프 자동 생성 │
│ • 난이도 3단계 (A/B/C) │
│ • 병렬 처리 (ThreadPoolExecutor) │
│ │
│ Korean Service: │
│ • 유형별 핵심 발췌 (Context Engineering) │
│ - 소설: 갈등/대화 중심 (800-1200자) │
│ - 비문학: 논지/증거 중심 (800-1200자) │
│ • 작품별 병렬 생성 (max_workers=5) │
│ • Input Token 92% 절감 │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ [5] AI Judge 검증 (GPT-4o-mini) - 각 문제별 │
│ │
│ 검증 기준 (1-5점): │
│ ┌────────────────────────────────────────────────┐ │
│ │ Math: │ │
│ │ • mathematical_accuracy (수학적 정확성) │ │
│ │ • consistency (정답 일치도) ≥ 4.0 (필수) │ │
│ │ • completeness (완결성) │ │
│ │ • logic_flow (논리성) │ │
│ ├────────────────────────────────────────────────┤ │
│ │ Korean: │ │
│ │ • literary_accuracy / narrative_comprehension │ │
│ │ • relevance (지문 관련성) │ │
│ │ • textual_analysis / critical_thinking │ │
│ │ • answer_clarity (정답 명확성) │ │
│ └────────────────────────────────────────────────┘ │
│ │
│ 합격 조건: 모든 점수 ≥ 3.5 (또는 consistency ≥ 4.0) │
└──────────────────────────┬──────────────────────────────────────┘
│
┌──────────┴──────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ VALID │ │ INVALID │
│ (합격) │ │ (불합격) │
└──────┬───────┘ └──────┬───────┘
│ │
│ 피드백 저장:
│ • 점수: {accuracy: 3.0, ...}
│ • 이슈: "정답 불일치"
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ [6] 재시도 메커니즘 (최대 3회) │
│ │
│ len(valid_problems) < target_count? │
│ ├─ NO → [7] DB 저장 (성공) │
│ └─ YES → 피드백 기반 프롬프트 재구성 │
│ │
│ 재구성 프롬프트 예시: │
│ """ │
│ **IMPORTANT: Previous attempt had issues. Fix these:** │
│ │
│ Problem 1 feedback: │
│ - Scores: consistency=2.5, accuracy=4.0 │
│ - Issue: 풀이 과정의 마지막 답이 정답과 일치하지 않습니다 │
│ │
│ **MUST ensure**: consistency ≥ 4.0, all scores ≥ 3.5 │
│ """ │
│ │
│ → [4] AI 문제 생성으로 돌아가 부족한 개수만 재생성 ◄────────┐
└──────────────────────────┬──────────────────────────────────────┘ │
▼ │
[목표 달성 시] [재시도 필요 시]
│ │
└─────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ [7] PostgreSQL 저장 │
│ • Worksheet 생성 │
│ • Problem 저장 (TikZ 코드 포함) │
│ • Transaction 커밋 │
└──────────────────────────┬──────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ [8] 실시간 알림 (Notification Service) │
│ • SSE (Server-Sent Events) 스트리밍 │
│ • 진행 상태: 대기 → 생성 중 → 검증 중 → 완료 │
│ • 사용자에게 실시간 피드백 │
└─────────────────────────────────────────────────────────────────┘
[핵심 성과]
• 초기 통과율: 78% (First-Pass Yield)
• 최종 합격률: 99% (Feedback-Enhanced Regeneration)
• 교육 품질 신뢰도: 95% (Independent AI Audit)
• 검증 비용: 전체 생성 비용의 0.8% (하이브리드 아키텍처)
교사 → Auth Service (인증) → Market Service
↓
상품 조회 → 포인트 차감
↓
판매자 수익 적립 (90%)
↓
Math/Korean/English Service → 워크시트 복사
↓
구매자 계정에 워크시트 추가
↓
구매 기록 저장 → 알림 전송
교사 → Korean Service → 과제 생성
↓
클래스룸 학생들에게 배포
↓
학생 답안 제출 (OCR 포함)
↓
AI 채점 (Gemini) → 피드백 생성
↓
채점 결과 저장 → 교사/학생 알림
# Database
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=qt_project_db
# AI API Keys
GEMINI_API_KEY=your-gemini-key
MATH_GEMINI_API_KEY=your-math-gemini-key (optional)
KOREAN_GEMINI_API_KEY=your-korean-gemini-key (optional)
ENGLISH_GEMINI_API_KEY=your-english-gemini-key (optional)
OPENAI_API_KEY=your-openai-key
GOOGLE_VISION_API_KEY=your-vision-key (optional)
# Auth
AUTH_SECRET_KEY=your-jwt-secret-key
# Redis
REDIS_URL=redis://redis:6379/0| 서비스 | 외부 포트 | 내부 포트 | 스키마 |
|---|---|---|---|
| Math Service | 8001 | 8000 | math_service |
| English Service | 8002 | 8000 | english_service |
| Auth Service | 8003 | 8000 | auth_service |
| Korean Service | 8004 | 8000 | korean_service |
| Market Service | 8005 | 8000 | market_service |
| Notification Service | 8006 | 8000 | notification_service |
| PostgreSQL | 5433 | 5432 | - |
| Redis | 6379 | 6379 | - |
# 1. 환경 변수 설정
cp .env.example .env
# .env 파일 수정
# 2. Docker Compose로 모든 서비스 실행
docker-compose up -d
# 3. 로그 확인
docker-compose logs -f
# 4. 특정 서비스만 재시작
docker-compose restart math-service
# 5. 전체 종료
docker-compose down# Math Service
cd services/math-service
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
# Math Celery Worker
celery -A app.celery_app worker --loglevel=info
# Korean Service
cd services/korean-service
pip install -r requirements.txt
python korean_main.py
# Korean Celery Worker
celery -A app.celery_app worker --loglevel=info --concurrency=4
# Auth Service
cd services/auth-service
pip install -r requirements.txt
uvicorn auth_main:app --reload --port 8000
# Market Service
cd services/market-service
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000각 서비스는 자동 생성된 API 문서를 제공합니다:
- Math Service: http://localhost:8001/docs
- English Service: http://localhost:8002/docs
- Auth Service: http://localhost:8003/docs
- Korean Service: http://localhost:8004/docs
- Market Service: http://localhost:8005/docs
- Notification Service: http://localhost:8006/docs
- 로그인: 사용자가 Auth Service로 로그인
- 토큰 발급: JWT 토큰 생성 (7일 유효)
- 토큰 검증: 다른 서비스가 Auth Service의
/api/auth/verify-token으로 검증 - 권한 확인: 교사/학생 역할 기반 접근 제어
- JWT 토큰 기반 stateless 인증
- bcrypt 비밀번호 해싱 (rounds=12)
- CORS 설정 (프론트엔드 도메인만 허용)
- 서비스 간 내부 통신 (Docker 네트워크)
- 환경 변수로 민감 정보 관리
services/디렉토리에 새 서비스 폴더 생성Dockerfile및requirements.txt작성docker-compose.yml에 서비스 추가- PostgreSQL 스키마 생성 (
scripts/init-schema.sql) - Auth Service 미들웨어 연동
- README.md 작성
# 스키마 초기화 (주의: 데이터 손실)
docker-compose down -v
docker-compose up -d postgres
# 특정 서비스 스키마만 재생성
docker exec -it qt_project_db psql -U postgres -d qt_project_db
DROP SCHEMA math_service CASCADE;
# 서비스 재시작하면 자동 생성- Celery Worker: 로컬에서는
--pool=solo옵션 사용 - Redis: Docker로 실행하고 로컬에서 연결
- PostgreSQL: pgAdmin 또는 DBeaver로 DB 관리
- Hot Reload:
--reload옵션으로 자동 재시작
- 포트 충돌:
docker-compose down후 재시작 - DB 연결 실패: PostgreSQL 컨테이너 상태 확인
- Celery 작업 실패: Redis 연결 및 Worker 로그 확인
- AI API 에러: API 키 유효성 및 할당량 확인
- 인증 실패: Auth Service 상태 및 토큰 만료 확인
# 전체 서비스 로그
docker-compose logs -f
# 특정 서비스 로그
docker-compose logs -f math-service
# Celery Worker 로그
docker-compose logs -f celery-worker