TinyTalk
TinyTalk Study
Technical Plan
TinyTalk Study
기술 기획서
1. Technical Overview
1. 기술 개요
TinyTalk Study is built on a Flutter mobile app + PHP/MySQL backend architecture, integrating OpenAI (STT/GPT), ElevenLabs (TTS), HeyGen (video avatar), and Live2D (character avatar).
TinyTalk Study는 Flutter 모바일 앱 + PHP/MySQL 백엔드 아키텍처로 구축되며, OpenAI(STT/GPT), ElevenLabs(TTS), HeyGen(영상 아바타), Live2D(캐릭터 아바타)를 통합합니다.
25+
API Endpoints
API 엔드포인트
11
Admin Modules
관리자 모듈
12
DB Tables
DB 테이블
5
External APIs
외부 API
2. System Architecture
2. 시스템 아키텍처
┌─────────────────────────────────────────────────────────────────┐
│ tinytalkstudy.com │
├──────────────┬────────────────────┬─────────────────────────────┤
│ Landing │ Admin Web │ REST / SSE API │
│ index.html │ /admin/ │ /api/*.php │
│ policy.html │ PHP Session Auth │ PHP 8.x + MySQL │
│ tos.html │ CSRF Protected │ Bearer Token (App) │
└──────┬───────┴─────────┬──────────┴──────────────┬──────────────┘
│ │ │
┌──────▼─────────────────▼───────────────────────────▼──────────────┐
│ Flutter Mobile App │
│ Android (com.tinytalkstudy.tinytalk_study) │
│ iOS (TinyTalk) │
└──────────────────────────┬───────────────────────────────────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
OpenAI ElevenLabs HeyGen
Whisper STT TTS Stream LiveAvatar
GPT-4o (Proxy) + LiveKit WebRTC
│
▼
Live2D (In-App)
CDN: /assets/live2d/
3. Technology Stack
3. 기술 스택
| Layer | 레이어 | Technology | 기술 | Notes | 비고 |
|---|---|---|---|---|---|
| Mobile App | 모바일 앱 | Flutter (Dart) | Android + iOS single codebase | Android + iOS 단일 코드베이스 | |
| Backend API | 백엔드 API | PHP 8.x, MySQL | Shared hosting, Apache | 공유 호스팅, Apache | |
| Landing / Docs | 랜딩 / 문서 | HTML, CSS, Vanilla JS | Static, EN/KO i18n | 정적, EN/KO 다국어 | |
| STT | OpenAI Whisper | OpenAI Whisper | |||
| LLM | GPT-4o | Streaming (SSE) + feedback | 스트리밍(SSE) + 피드백 | ||
| TTS | ElevenLabs | Audio streaming via PHP proxy | PHP 프록시 음성 스트리밍 | ||
| Video Avatar | 영상 아바타 | HeyGen + LiveKit | WebRTC real-time streaming | WebRTC 실시간 스트리밍 | |
| Character Avatar | 캐릭터 아바타 | Live2D Cubism | Custom Flutter plugin, Lottie fallback | 자체 Flutter 플러그인, Lottie 폴백 |
Flutter Key Packages
Flutter 주요 패키지
| Package | Purpose | 용도 |
|---|---|---|
record | Microphone PTT recording | 마이크 PTT 녹음 |
dio | HTTP client with retry | 재시도 HTTP 클라이언트 |
flutter_client_sse | GPT SSE streaming | GPT SSE 스트리밍 |
just_audio | TTS playback | TTS 재생 |
livekit_client | HeyGen WebRTC | HeyGen WebRTC |
flutter_live2d | Live2D rendering (local) | Live2D 렌더링 (로컬) |
lottie | Character emotion fallback | 캐릭터 감정 폴백 |
4. Implementation Status
4. 구현 현황
MVP Phases
MVP 단계
| Phase | Scope | 범위 | Status | 상태 |
|---|---|---|---|---|
| MVP 1 | PTT → STT → GPT → text display + log save | PTT → STT → GPT → 텍스트 표시 + 로그 저장 | Done완료 | |
| MVP 2 | GPT streaming + sentence TTS | GPT 스트리밍 + 문장 단위 TTS | Done완료 | |
| MVP 3 | Video avatar (HeyGen) | 영상 아바타 (HeyGen) | Done완료 | |
| MVP 3+ | Live2D character avatar (Replika UX) | Live2D 캐릭터 아바타 (Replika형 UX) | Asset production에셋 생산 중 | |
| MVP 4 | Learning reports, missions, B2B assignment | 학습 리포트, 미션, B2B 배정 | Planned예정 |
Platform Components
플랫폼 구성요소
| Component | 구성요소 | URL / Path | Status | 상태 |
|---|---|---|---|---|
| Landing Page | 랜딩 페이지 | / | ✓ | |
| Service Plan (this doc) | 서비스 기획서 | /service.html | ✓ | |
| Technical Plan (this doc) | 기술 기획서 | /technical.html | ✓ | |
| Flutter App | Flutter 앱 | Android / iOS | ✓ | |
| REST/SSE API | REST/SSE API | /api/ | ✓ | |
| Admin Panel | 관리자 패널 | /admin/ | ✓ | |
| Live2D CDN Assets | Live2D CDN 에셋 | /assets/live2d/ | In progress진행 중 |
5. AI Conversation Pipeline
5. AI 대화 파이프라인
User PTT
사용자 PTT
→
stt_upload.php
→
gpt_stream.php
→
Response Mode
응답 모드
→
DB Save
| Response Mode | 응답 모드 | Output | 출력 | Technology | 기술 |
|---|---|---|---|---|---|
| Text | 텍스트 | Chat bubble UI | 채팅 버블 UI | GPT-4o | |
| Audio / TTS | 오디오 / TTS | Voice playback | 음성 재생 | ElevenLabs | |
| Video (HeyGen) | 영상 (HeyGen) | LiveKit WebRTC stream | LiveKit WebRTC 스트림 | HeyGen LiveAvatar | |
| Video (Replika) | 영상 (Replika) | Live2D + lip-sync + emotions | Live2D + 립싱크 + 감정 | Live2D Cubism |
Character Emotion States
캐릭터 감정 상태
idle
listening
thinking
speaking
praise
review
error
6. Dual Avatar Strategy
6. 듀얼 아바타 전략
| Mode | 모드 | Provider | 제공자 | Use Case | 용도 | Cost | 비용 |
|---|---|---|---|---|---|---|---|
| Video Avatar | 영상 아바타 | HeyGen | Premium demo, marketing, B2B showcase | 프리미엄 데모, 홍보, B2B 시연 | High (session/minute billing) | 높음 (세션·분 과금) | |
| Character Avatar | 캐릭터 아바타 | Live2D | Daily learning, children & teens | 일상 학습, 아동·청소년 | Low (GPT+STT+TTS level) | 낮음 (GPT+STT+TTS 수준) |
Admin switch: avatar_provider in admin_settings — globally toggles between heygen and replika. App reads via get_app_config.php.
관리자 전환: admin_settings의 avatar_provider로 heygen ↔ replika 전역 전환. 앱은 get_app_config.php로 읽음.
7. API Reference
7. API 정리
Base URL: https://tinytalkstudy.com/api
Authentication
인증
| Endpoint | Method | Description | 설명 |
|---|---|---|---|
| /auth_register.php | POST | Register (email, PIN, name) | 회원가입 |
| /auth_login.php | POST | Login → Bearer Token | 로그인 → Bearer Token |
| /auth_logout.php | POST | Logout | 로그아웃 |
| /auth_me.php | GET | Current user info | 현재 사용자 정보 |
| /auth_profile.php | POST | Update profile | 프로필 수정 |
Chat Sessions
대화 세션
| Endpoint | Method | Description | 설명 |
|---|---|---|---|
| /create_session.php | POST | Create new session | 새 세션 생성 |
| /resume_session.php | POST | Resume today's session | 오늘 세션 재개 |
| /get_sessions.php | GET | Session list | 세션 목록 |
| /get_chat_history.php | GET | Message history | 메시지 히스토리 |
| /session_save.php | POST | Mark session saved | 세션 저장 |
| /session_summarize.php | POST | GPT session summary | GPT 세션 요약 |
AI Pipeline
AI 파이프라인
| Endpoint | Method | External | 외부 API | Description | 설명 |
|---|---|---|---|---|---|
| /stt_upload.php | POST | OpenAI Whisper | Audio → text | 음성 → 텍스트 | |
| /gpt_stream.php | SSE | GPT-4o | Streaming response | 스트리밍 답변 | |
| /gpt_feedback.php | POST | GPT-4o | Non-streaming response | 비스트리밍 답변 | |
| /elevenlabs_tts_stream.php | POST | ElevenLabs | TTS audio stream | TTS 음성 스트리밍 |
HeyGen
| Endpoint | Method | Description | 설명 |
|---|---|---|---|
| /heygen_session.php | GETPOST | Create streaming session | 스트리밍 세션 생성 |
| /heygen_start.php | POST | WebRTC SDP | WebRTC SDP |
| /heygen_ice.php | POST | ICE candidate | ICE candidate |
| /heygen_task.php | POST | Avatar speak | 아바타 발화 |
| /heygen_stop.php | POST | Session stop | 세션 종료 |
Character / Config
캐릭터 / 설정
| Endpoint | Method | Description | 설명 |
|---|---|---|---|
| /get_app_config.php | GET | Avatar provider, flags, default character | 아바타 제공자, 플래그, 기본 캐릭터 |
| /get_character.php | GET | Character + emotions | 캐릭터 + 감정 모션 |
| /get_user_character.php | GET | Assigned character for user | 사용자 배정 캐릭터 |
Operations
운영
| /health.php | GET | API health check | API 상태 확인 |
| /cleanup_uploads.php | GET | Cron upload cleanup (token) | Cron 업로드 정리 |
8. External API Integration
8. 외부 API 연동
| Service | 서비스 | Purpose | 용도 | Integration | 연동 | Billing | 과금 |
|---|---|---|---|---|---|---|---|
| OpenAI Whisper | STT | PHP backend proxy | PHP 백엔드 프록시 | Usage-based | 사용량 과금 | ||
| OpenAI GPT-4o | Chat, feedback, summary | 대화, 피드백, 요약 | PHP proxy (SSE) | PHP 프록시 (SSE) | Token-based | 토큰 과금 | |
| ElevenLabs | TTS | PHP proxy (streaming) | PHP 프록시 (스트리밍) | Char/minute | 문자/분 과금 | ||
| HeyGen LiveAvatar | Video avatar | 영상 아바타 | PHP + LiveKit WebRTC | Session/minute (high) | 세션·분 (고비용) | ||
| Live2D Cubism | Character animation | 캐릭터 애니메이션 | Flutter in-app + CDN | Flutter 앱 + CDN | SDK license (TBD) | SDK 라이선스 (검토) |
Usage logging: All external API calls are logged to api_usage_logs table (service, tokens, latency). Visible in Admin → API Usage.
사용량 로깅: 모든 외부 API 호출은 api_usage_logs 테이블에 기록 (서비스, 토큰, 지연시간). 관리자 → API 사용량에서 확인.
9. Database Schema
9. 데이터 모델
| Table | 테이블 | Purpose | 용도 |
|---|---|---|---|
users | App users (email, PIN, profile) | 앱 사용자 | |
user_auth_tokens | Bearer token auth | Bearer Token 인증 | |
ai_personas | AI personas (prompt, avatar ID) | AI 페르소나 | |
ai_characters | Live2D character master | Live2D 캐릭터 마스터 | |
character_emotions | 7 emotion motions per character | 캐릭터별 7종 감정 모션 | |
student_character_assignments | User ↔ character mapping (B2B) | 학생 ↔ 캐릭터 배정 | |
chat_sessions | Conversation sessions | 대화 세션 | |
chat_messages | Messages (text, audio URL) | 메시지 (텍스트, 오디오) | |
api_usage_logs | API usage per service | 서비스별 API 사용량 | |
admin_users | Admin accounts | 관리자 계정 | |
admin_settings | Global KV settings | 전역 설정 | |
prompt_history | Persona prompt audit trail | 프롬프트 변경 이력 |
Migrations: backend/sql/ (11 files)
마이그레이션: backend/sql/ (11개 파일)
10. Admin Panel Modules
10. 관리자 패널
URL: https://tinytalkstudy.com/admin/
PHP session auth, CSRF on all POST forms. Separate from app user auth.
PHP 세션 인증, 모든 POST에 CSRF. 앱 사용자 인증과 분리.
✓Dashboard대시보드
✓Member Management회원 관리
✓Conversations대화 관리
✓Prompt / Personas프롬프트 관리
✓HeyGen Avatar
✓Avatar Settings아바타 설정
✓AI CharactersAI 캐릭터
✓Character Assignments캐릭터 배정
✓API UsageAPI 사용량
✓Voice Storage음성 저장소
✓Settings설정
11. Technical Roadmap
11. 기술 로드맵
Replika Character Implementation Phases
Replika 캐릭터 구현 단계
| Phase | Scope | 범위 | Status | 상태 |
|---|---|---|---|---|
| Phase 0 | SQL, get_app_config, admin avatar settings | SQL, get_app_config, 관리자 아바타 설정 | Done완료 | |
| Phase 1 | Sprite/Lottie MVP, PTT↔emotion, TTS speaking | Sprite/Lottie MVP, PTT↔감정, TTS | Done완료 | |
| Phase 2 | Live2D upload, lip-sync, emotion admin | Live2D 업로드, 립싱크, 감정 관리자 | Done완료 | |
| Phase 3 | Student assignments, praise/review triggers | 학생 배정, 칭찬/복습 트리거 | Done완료 | |
| Phase 4 | HeyGen + Replika parallel QA, premium policy | HeyGen + Replika 병행 QA, 프리미엄 정책 | In progress진행 중 | |
| Step 5 | Custom Live2D model production (Cubism → CDN) | 커스텀 Live2D 모델 생산 (Cubism → CDN) | Asset work에셋 작업 |
Infrastructure Direction
인프라 방향
| Current | 현재 | Shared PHP hosting (tinytalkstudy.com) | 공유 PHP 호스팅 (tinytalkstudy.com) |
| Scale-up | 확장 | VPS / cloud migration when traffic grows | 트래픽 증가 시 VPS/클라우드 전환 |
| AI Model | GPT-4o maintained; Fine-tuning / RAG under review | GPT-4o 유지; Fine-tuning / RAG 검토 | |
| Flutter | Single codebase; Web unsupported for Live2D | 단일 코드베이스; Web은 Live2D 미지원 |