OOM | 오픽온미 (OPIc On Me)

OOM은 OPIc 영어 말하기를 Course × Level 구조로 연습하는 브라우저 기반 정적 웹앱입니다. 목표 설정부터 서베이, 스크립트, 롤플레이, 녹음과 복기까지 하나의 6단계 흐름으로 연결합니다. 실제 점수나 등급을 보장하지 않으며, 익숙한 장면을 여러 질문에 맞게 바꾸어 말하는 연습에 초점을 둡니다.

Product model

• Course는 서베이 조합, 이야기 세계, 롤플레이, 실전 질문을 소유합니다.
• Level은 난이도, 답변 밀도, 목표 발화 시간을 소유합니다.
• 현재 Level은 1구간 · AL · 60~90초, 2구간 · IH / IM3 · 45~65초, 3구간 · IM2 / IM1 · 30~45초입니다.
• 현재 등록된 Course는 Everyday & Getaway, Culture & City, Nature & Weekend입니다. Course registry는 폴더를 자동 발견하므로 Course 수를 세 개로 고정하지 않습니다.

훈련 흐름은 다음과 같습니다.

1. STEP 1 목표 구간 · 코스 설정 — /training/setup/
2. STEP 2 추천 서베이 익히기 — /training/survey/
3. STEP 3 난이도 설정 — /training/difficulty/
4. STEP 4 만능 스크립트 — /training/scripts/
5. STEP 5 롤플레이 공식 — /roleplay/
6. STEP 6 실전 연습 — Hub /practice/, 빠른 연습 /practice/quick/, 실전 모의고사 /practice/mock/

/는 AppShell과 분리된 제품 랜딩이고, /about/는 OOM 학습 방식, /exam-guide/는 수험 가이드, /magazine/은 정적 학습 콘텐츠입니다. STEP 2~6은 유효한 TrainingSelection이 있어야 하며, 선택이 없을 때 임의 Course나 Level로 넘어가지 않습니다.

Main capabilities

• Course별 한 canonical storyline을 세 Level에서 같은 장면으로 확장
• STEP 4의 OPEN → SCENE → CLOSE, 질문 변형, KEEP / CHANGE / DROP
• STEP 5의 CORE 기능과 OPTIONAL 기능을 고르는 6-function menu
• STEP 6 빠른 연습과 실전 모의고사, 질문 청취 0/2 제한, MediaRecorder 녹음, 다시 듣기
• 실전 모의고사의 Background Survey → Self Assessment → 시험 준비 → 자기소개 워밍업 → 1st Session → 난이도 재조정 → 2nd Session → 결과 요약 / 답변 복기 / 훈련 리포트
• optional STT 전사, editable transcript, 사용자 설정 LLM 기반 KEEP / FIX / RETRY 피드백
• 모든 LLM 기능의 자동 라우팅: 커스텀 endpoint가 있으면 브라우저에서 직접 호출하고, 없으면 로그인 기반 관리형 AI 사용 (서버 기본 OFF; 배포 절차)
• Heart / Bella / Sarah / Sky 4개 음성과 744개 정적 WebM/Opus 음원·피크 자산을 먼저 쓰는 static-first TTS, WaveSurfer waveform
• 고정 콘텐츠는 빌드된 정적 음원을 우선 재생하고 누락 시에만 Kokoro 브라우저 합성 및 Web Speech로 폴백

STEP 6의 빠른 연습은 자기소개 워밍업 없이 한 문제를 바로 듣고 녹음한 뒤 STT·AI로 복기합니다. 실전 모의고사는 현재 Course의 설문을 확인하고 Mock 전용 Self Assessment Level을 고른 뒤, 문항 수와 40분 타이머에 포함되지 않는 20~30초 자기소개 워밍업을 거쳐 두 Session을 이어갑니다. Survey와 Mock Level은 현재 세션 메모리에만 있으며 저장된 TrainingSelection을 바꾸지 않습니다. 시험 중에는 STT·AI·transcript·힌트를 호출하거나 표시하지 않습니다. 종료 후에는 결과 요약, 답변 복기, 훈련 리포트를 같은 세션에서 오가며 확인합니다. 훈련 리포트는 완료율, 목표 발화 시간 적합도, 녹음과 답변 시간, 선택적으로 수행한 STT·AI 복기 범위만 보여 주며 점수나 예상 OPIc 등급을 산출하지 않습니다. 리포트는 서버 전송 없이 standalone HTML로 내려받을 수 있습니다.

Tech stack

• Vite + React 18 + TypeScript
• React Router, Tailwind CSS, Framer Motion, GSAP, Lenis, React Three Fiber
• Kokoro-82M via kokoro-js, WaveSurfer, browser Web Speech fallback
• Vitest + Testing Library
• GitHub Pages 또는 일반 정적 호스팅

프런트엔드는 GitHub Pages 정적 배포를 유지하며 Supabase를 외부 인증·프로필 서비스로 사용합니다. Google 로그인과 마이페이지를 통해 계정 정보, 목표 설정 상태, 최근 학습 기록을 관리할 수 있으며, 로그인 없이도 기존 훈련과 공개 콘텐츠를 자유롭게 이용할 수 있습니다. 설정은 Supabase Setup을 참고하세요. LLM/STT endpoint·model은 브라우저 localStorage에 저장됩니다. 커스텀 LLM endpoint가 설정되어 있으면 모든 LLM 기능에서 자동으로 우선 사용하고, 없으면 관리형 AI를 사용합니다(관리형 AI 서버는 기본 OFF 상태이며 관리자 배포 전에는 custom endpoint 또는 로그인 안내가 적용됩니다). API key는 기본적으로 탭 sessionStorage를 사용하며, 사용자가 “이 기기에 API Key 저장”을 선택하고 저장한 경우에만 localStorage에 평문으로 영구 저장됩니다(공용 PC 주의). 커스텀 STT 사용 시 녹음된 오디오는 브라우저에서 사용자가 설정한 외부 STT 엔드포인트로 직접 전송됩니다. 소스에는 키를 포함하지 않습니다. STT 설정 key는 oom-stt-settings입니다.

Local development

Node.js 22 이상이 필요하며 CI와 같은 Node.js 24를 권장합니다.

npm install
npm run dev

기본 개발 주소는 http://localhost:5173입니다.

Commands

npm run lint
npm run test
npm run build
npm run verify:pages
npm run preview
npm run docs:generate
npm run docs:check
npm run tts:audit
npm run tts:validate -- --prune-dry-run

npm run build는 TypeScript와 Vite 빌드 후 scripts/generate-static-routes.mjs로 canonical route별 dist/**/index.html(총 73개 사전 렌더링 정적 HTML, 48개 sitemap 색인 대상)을 생성합니다. npm run verify:pages는 crawler-visible 본문, canonical URL, bundle 참조, Pages 필수 파일을 검사합니다.

TTS 콘텐츠를 추가하거나 수정했다면 Content Authoring의 순서를 따릅니다. npm run tts:generate는 FFmpeg/ffprobe가 있는 개발자 PC에서 실행하며, 출력된 dev URL에서 생성 시작을 눌러야 합니다. 이미 검증된 동일 hash/voice asset은 건너뛰고 누락분만 생성합니다. CI에서는 음원을 생성하지 않습니다.

Documentation map

문서	분류	역할
AGENTS.md	CANONICAL	code agent 운영 규칙과 금지사항
Architecture	CANONICAL	runtime ownership와 browser/backend boundary
Training System	CANONICAL	Course × Level, STEP 1~6, guard와 UI contract
Content Authoring	CANONICAL	새 Course·script·question 추가 절차
TTS Audio Pipeline	CANONICAL	static-first TTS 생성·runtime·asset 정책
Routing	CANONICAL	route, sidebar, training header contract
Deployment	CANONICAL	GitHub Pages build와 future intranet boundary
Static-first TTS ADR	HISTORICAL DECISION	TTS 선택의 배경과 결과
Project Snapshot	GENERATED	package scripts와 src/ inventory
artifacts/tts-inventory.json	GENERATED DEV INPUT	tts:audit이 만들고 generator/validator가 읽는 inventory
docs/AUDIT_*.md, docs/IMPLEMENTATION_AUDIT_RESOLUTION.md, docs/TRAINING_CONTENT_QA.md	HISTORICAL	특정 시점의 감사와 해결 기록; 현재 architecture source가 아님
Magazine Image Sources	PROVENANCE	매거진 생성 이미지의 제작 방식과 파일 기록

Deployment summary

.github/workflows/pages.yml이 main 또는 feature/adsense push에서 lint, generated docs check, tests, build, Pages artifact 검증 후 dist/를 배포합니다. Vite base는 /이고 canonical origin은 https://opic-on-me.com입니다. 정적 TTS audio, peaks, production manifest는 public/generated-tts/에서 build artifact로 복사됩니다.

자세한 배포 구조와 project-subpath 주의사항은 Deployment를 참고하세요.

Phase 2.8 학습 허브와 요금제

마이페이지는 목표 설정, 서베이 준비, 만능 스크립트, 롤플레이, 실전 연습 바로가기를 제공합니다. 연습 세션은 기존 learning_sessions / learning_attempts에, 명시적 학습 완료는 learning_activity_events에 별도로 보관합니다. 계정 설정은 learning_preferences가 소유합니다.

This is the beginning of the README. Read the rest at the original. Read the full README ↗