iRead

아동의 읽기 특성을 이해하는 개인화 읽기 훈련 시스템

개발 인원 6명
개발 기간 2026.07.06 ~ 2026.08.10 (6주)
플랫폼 교수자 Web · 아동 Windows Electron App
프로젝트 자료 발표 자료 보기 · 소개 영상 보기

📑 목차

📌 서비스 소개
👥 팀원 소개 및 역할
✨ 주요 기능
🛠️ 기술 스택
🏗️ 시스템 아키텍처
🗄️ ERD
📋 API 명세
🔬 핵심 기술 상세

📌 서비스 소개

iRead는 읽기에 어려움을 겪는 초등학교 저학년 난독증 아동을 위한 시선·발음 데이터 기반 맞춤형 읽기 훈련 서비스입니다.

아동은 이야기와 놀이로 구성된 콘텐츠를 통해 즐겁게 읽기 훈련을 이어갈 수 있고, 교수자는 훈련 중 수집된 시선·발음·학습 데이터를 통해 아동이 어떤 부분에서 어려움을 겪는지 파악하고 학습 변화를 확인할 수 있습니다.

기획 배경

기존의 읽기 학습 결과만으로는 아동이 글을 읽는 동안 어디에서 머뭇거리는지, 어떤 단어나 문장을 어려워하는지 구체적으로 파악하기 어렵습니다.

iRead는 아동이 글을 읽는 동안의 시선과 발음을 분석해 읽기 특성을 파악하고, 그 결과를 바탕으로 아동에게는 맞춤형 훈련을, 교수자에게는 상세한 리포트를 제공합니다.

대상 사용자

사용자	제공 가치
아동	이야기와 놀이를 통해 자신의 수준에 맞는 읽기 훈련을 진행합니다.
교수자	시선·발음·학습 데이터를 바탕으로 아동의 읽기 과정과 변화를 확인하고, 커리큘럼을 관리합니다.
보호자	보고서를 통해 아동의 학습 현황과 성장 과정을 확인할 수 있습니다.

핵심 가치

읽는 과정까지 들여다보는 분석
정답과 점수뿐 아니라 시선과 발음까지 함께 분석해 아동이 글을 읽어가는 과정을 살펴봅니다.
아동 맞춤형 읽기 훈련
아동 개개인의 읽기 특성과 학습 진행 상황을 반영한 맞춤형 훈련을 제공합니다.
한눈에 보이는 학습 변화
훈련 결과와 검사 데이터, 학습 변화 추이를 교수자 화면과 리포트로 한눈에 확인할 수 있습니다.
즐겁게 지속하는 학습 경험
이야기와 상호작용 중심의 콘텐츠로 아동이 읽기 훈련을 부담 없이 꾸준히 이어갈 수 있도록 돕습니다.

👥 팀원 소개 및 역할

윤정 PM · 백엔드 `dbswjd0191a`	김지훈 교수자 웹 백엔드 `2hnK`	정의찬 아동 앱 백엔드 `uichan01`
담당 기능 프로젝트 관리 · 커리큘럼 및 훈련 백엔드 주요 구현 내용 훈련 카탈로그와 문항 정책 정리 커리큘럼 교안 자동 생성 연동 진단 문항·발음 평가·성장 정보 API 안정화	담당 기능 교수자 웹 API · 학습 및 이야기 관리 주요 구현 내용 학습 현황·이력·보고서 API 구현 커리큘럼·교안 편집 계약 구현 SSE 학습 상태와 이야기·이미지 관리 연동	담당 기능 아동 앱 API · 훈련 및 이야기 실행 주요 구현 내용 훈련 제출·진행·재진입과 성장 정보 API 연동 이야기 분기 생성 중복 제어 교안 생성 완료 실시간 알림 구현
김민재 프론트엔드 `minjaekim1122`	이승환 인프라 · 아이트래커 `wanderingperson`	송승우 AI `themancalledsong`
담당 기능 교수자 웹 프론트엔드 주요 구현 내용 학습 현황·이력·보고서 화면 구현 커리큘럼·교안 편집 UI 구현 이야기 이미지 재생성과 시선 리플레이 연동	담당 기능 배포 인프라 · Tobii 아이트래커 주요 구현 내용 AWS·Nginx·Docker Compose 배포 환경 구성 Tobii 보정·연결 상태·자동 실행 구현 단어별 시선 수집·분석·리플레이 구현	담당 기능 개인화 학습 · 생성형 AI · 발음 평가 주요 구현 내용 읽기 프로필 기반 커리큘럼·교안 생성 및 검증 개인화 이야기·장면 이미지 생성 API 구현 Azure Speech 발음 평가 피드백 구현

✨ 주요 기능

기능	설명
📚 개인화 읽기 훈련	아동 앱에서 배정된 커리큘럼을 열고 글자 따라 읽기, 첫소리 찾기, 소리 합치기, 문장 만들기 등의 훈련을 진행합니다.
👁️ 시선 기반 읽기 분석	Tobii Eye Tracker로 훈련 중 시선을 수집하고 화면의 단어·문장 영역과 연결해 머문 시간, 건너뜀, 되읽기 정보를 기록합니다.
🗣️ 단어별 발음 평가	마이크로 수집한 읽기 음성을 Azure Speech로 분석해 단어별 정확도와 오류 유형을 표시합니다.
✨ AI 이야기 학습	아동의 학습 진행과 선택을 반영해 이야기와 장면 이미지를 생성하고, 이야기 화면에서 읽기와 선택 활동을 진행합니다.
📊 교수자 학습 관리	교수자 웹에서 커리큘럼을 생성·편집하고 아동별 학습 현황, 학습 이력, 분석 보고서와 이야기 기록을 조회합니다.

1. 개인화 읽기 훈련

아동 앱 로그인 및 학습 영역 선택 _{아동 프로필로 로그인한 뒤 학습 섬에서 진행할 영역을 선택합니다.}
글자 따라 읽기 _{제시된 글자의 획순을 확인하고 마이크로 소리 내어 읽습니다.}	소리 합치기 _{제시된 소리 조각을 순서대로 합쳐 알맞은 낱말을 완성합니다.}
첫소리 찾기 _{낱말의 첫소리를 듣고 보기에서 알맞은 글자를 고릅니다.}	문장 만들기 _{낱말 카드를 문장 순서에 맞게 배치해 문장을 완성합니다.}

2. 시선 기반 읽기 분석

그림에 맞는 문장 찾기
그림의 내용을 확인하고 세 개의 보기에서 알맞은 문장을 선택합니다.

훈련 중 Tobii Eye Tracker가 수집한 시선 좌표를 화면의 그림과 문장 영역에 연결해 머문 시간, 건너뜀과 되읽기 정보를 기록합니다.

3. 단어별 발음 평가

낱말 읽기와 발음 평가
화면에 제시된 낱말을 마이크로 읽고 단어별 발음 평가를 진행합니다.

Azure Speech의 한국어 발음 평가가 읽기 음성을 분석하고 단어별 정확도와 오류 유형을 제공합니다.

4. AI 이야기 학습

	이야기 선택 이야기를 읽은 뒤 질문에 답하며 다음 장면의 흐름을 선택합니다. 아동의 학습 진행을 반영해 생성된 이야기와 장면 이미지를 읽고 화면의 선택지에서 다음 내용을 고릅니다.
	새 이야기 생성 학습을 마친 뒤 새로운 이야기 생성을 요청합니다. 아동의 학습 진행을 반영한 이야기 본문과 장면 이미지를 생성합니다.

5. 교수자 학습 관리

학습 분석 보고서
아동별 학습 참여, 발음 정확도, 읽기 속도와 기간별 변화 추이를 확인합니다.

보고서 화면에는 학습 참여 일수, 총 학습 시간과 총 학습 횟수가 함께 표시됩니다.

교수자 관리 화면

AI 커리큘럼 생성 _{아동과 학습 기간을 선택해 개인화 커리큘럼 생성을 요청합니다.}	커리큘럼 교안 편집 _{훈련별 문항, 정답, 보기와 안내 내용을 확인하고 수정합니다.}
학습 현황 _{아동의 학습 진행률과 지표별 변화 추이를 조회합니다.}	학습 이력 _{회차별 훈련 결과와 문항별 상세 기록을 확인합니다.}
이야기 이미지 재생성 _{이야기 장면과 생성 정보를 확인하고 필요한 이미지를 다시 생성합니다.}	이야기 읽기 리플레이 _{이야기 페이지와 함께 단어별 시선 이동과 읽기 기록을 재생합니다.}

🛠️ 기술 스택

분류	기술
Frontend Web
Frontend App
Backend
AI Server
Database
Infrastructure
Eye Tracking

🏗️ 시스템 아키텍처

시선 데이터 흐름도 보기

요약 흐름도

상세 흐름도

🗄️ ERD

📋 API 명세

Swagger API 명세 보기

🔬 핵심 기술 상세

아동의 학습 데이터가 수집되고 분석되어 다음 학습으로 이어지는 과정을 중심으로 정리합니다.

1. 시선 데이터 수집 및 분석

Electron IPC와 로컬 시선 추적 bridge를 통해 Tobii Eye Tracker의 시선 프레임을 아동 앱으로 전달합니다. 수집한 좌표는 화면 요소와 매칭해 단어별 머문 시간, 건너뜀, 되읽기 등의 지표로 변환합니다. 장치 연결이 어려운 개발 환경에서는 마우스 기반 입력으로 전체 흐름을 검증할 수 있도록 구성했습니다.

2. 발음 평가

AI server가 Azure Speech의 한국어 발음 평가를 호출하고, 단어별 정확도와 오류 유형을 Backend에 전달합니다. Backend는 기준 문장과 분석 결과의 단어 순서를 검증한 뒤 학습 결과로 저장합니다. 음성 원본은 분석 과정에서만 사용하며, 처리가 끝나면 별도로 보관하지 않습니다.

3. 개인화 훈련 구성

완료된 학습에서 정답 여부, 발음 정확도, 시선 부담과 응답 지연을 읽기 특성별로 집계합니다. 분석된 취약 특성을 기준으로 직접 보완 훈련, 확장 훈련, 복습 훈련을 조합해 다음 학습을 구성합니다. 생성 결과는 문제 형식과 정답, 필수 입력 조건을 검증하며, 검증에 실패한 결과는 저장하지 않습니다.

4. AI 이야기 생성

아동의 학습 진행과 선택을 바탕으로 다음 이야기와 장면 이미지를 생성합니다. 생성된 페이지는 필수 구성과 내용 품질을 확인하며, 검증에 실패하면 제한된 횟수만큼 다시 생성합니다. 최종 검증을 통과한 경우에만 이야기를 저장해 불완전한 콘텐츠가 노출되지 않도록 합니다.

5. 실시간 학습 연동

아동 앱과 교수자 Web은 서로 직접 연결하지 않고, Backend의 인증된 SSE 연결을 통해 상태를 전달합니다. 훈련 시작과 완료, 학습 정보 변경 등의 이벤트가 발생하면 관련 데이터를 다시 조회하도록 하며, heartbeat와 재연결 처리로 화면 상태를 유지합니다.

🚀 개발자 가이드 (빌드·실행)

사전 준비

도구	용도
Git	루트 저장소와 submodule 내려받기
Docker Desktop	통합 데모 환경 실행
Node.js·pnpm	교수자 Web과 아동 App 개발·검증
Java 21	Spring Boot Backend 실행·검증
Python 3.12·uv	AI server 실행·검증
Windows·Tobii SDK	실제 Eye Tracker를 사용하는 경우에만 필요

저장소 받기

git clone --recurse-submodules https://github.com/iRead-B105/iRead.git
cd iRead

이미 루트 저장소만 clone했다면 submodule을 초기화합니다.

git submodule update --init --recursive

통합 데모 실행

Docker Compose로 전체 서비스를 실행합니다.

cp .env.example .env
docker compose up -d

Windows에서 각 서비스를 로컬 프로세스로 실행하려면 .env.example을 .env로 복사한 뒤 다음 스크립트를 사용할 수 있습니다.

.\start-all-local.bat

서비스	주소
교수자 Web	`http://localhost:5173`
아동 App	`http://localhost:5174`
Backend API	`http://localhost:8080`
AI server	`http://localhost:8081`
Mailpit	`http://localhost:8025`

서비스별 검증

아래 명령은 저장소 루트에서 각 서비스 디렉터리로 이동해 실행합니다.

# Frontend Web
cd services/frontend-web
pnpm install
pnpm build
pnpm test
cd ../..

# Frontend App
cd services/frontend-app
pnpm install
pnpm build
pnpm test
cd ../..

# Backend
cd services\backend
.\gradlew.bat test
cd ..\..

# AI server
cd services\ai
uv sync --extra dev
uv run pytest
cd ..\..

Tobii Eye Tracker를 사용할 때는 Windows에서 시선 추적 bridge를 먼저 실행합니다.

cd services\eyetracking
.\run_server.bat
cd ..\..

📁 디렉터리 구조

iRead/
├─ services/
│  ├─ backend/          # Spring Boot API와 데이터 처리
│  ├─ frontend-web/     # 교수자용 Vue Web
│  ├─ frontend-app/     # 아동용 Vue·Electron App
│  ├─ ai/               # FastAPI 기반 AI 기능
│  └─ eyetracking/      # Tobii 시선 수집·보정 bridge
├─ contracts/
│  ├─ openapi/          # App·Admin·Auth·AI API 계약
│  └─ database/         # MySQL 스키마와 ERD
├─ docs/                # 제품·아키텍처·결정·계획 문서
│  └─ assets/readme/
│     ├─ api/           # Swagger 명세 이미지
│     ├─ architecture/  # 시스템·데이터 흐름도
│     └─ features/
│        ├─ child-app/  # 아동 앱 공통 화면 GIF
│        ├─ training/   # 아동 읽기 훈련 GIF
│        ├─ story/      # AI 이야기 학습 GIF
│        └─ teacher/    # 교수자 관리 화면 GIF
├─ design-resources/    # UI와 콘텐츠 제작 원본
├─ tools/               # 계약·문서·통합 데모 검증 도구
├─ compose.yml          # 로컬 통합 실행 구성
├─ .env.example         # 환경 변수 예시
└─ README.md

services/*는 각각 독립된 Git 저장소이며 루트 저장소에는 submodule로 연결됩니다.

🌿 브랜치 전략 & 커밋 컨벤션

브랜치 전략

브랜치	용도
`main`	배포 가능한 릴리스 이력
`develop`	다음 릴리스의 통합 기준
`feature/*`	기능 개발과 검토가 필요한 변경
`release/*`	정식 릴리스 안정화
`hotfix/*`	운영 버전 긴급 수정

커밋 컨벤션

<type>(<scope>): <한국어 제목>

Type	용도
`feat`	사용자 기능 추가
`fix`	오류 수정
`docs`	문서 변경
`refactor`	동작 변경 없는 구조 개선
`test`	테스트 추가·수정
`perf`	성능 개선
`style`	동작과 무관한 서식 변경
`build`	빌드와 의존성 변경
`ci`	CI/CD 설정 변경
`chore`	기타 유지보수
`revert`	이전 커밋 되돌리기

Scope	용도
`feat(training)`	개인화 훈련 조회 기능 추가
`fix(gaze)`	시선 세션 종료 오류 수정
`docs(readme)`	프로젝트 소개 갱신

Name		Name	Last commit message	Last commit date
Latest commit History 284 Commits
.claude		.claude
.github		.github
contracts		contracts
design-resources		design-resources
docs		docs
exec		exec
plans		plans
services		services
tools		tools
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENTS.md		AGENTS.md
PLANS.md		PLANS.md
README.md		README.md
compose.qa-check.yml		compose.qa-check.yml
compose.yml		compose.yml
reset-qa-demo.bat		reset-qa-demo.bat
reset-qa-demo.sh		reset-qa-demo.sh
start-all-local.bat		start-all-local.bat

Uh oh!

Folders and files

Latest commit

History

Repository files navigation