README

Run

Prerequisites:

• Ruby 3.2.x
• Bundler
• SQLite3

Steps:

1. Install dependencies

bundle install

2. Set environment variables

• OPENAI_API_KEY (required for STT/LLM/TTS)

3. Prepare DB and seed data

bin/rails db:setup

4. Run server

bin/rails s

Design & Tech Stack Rationale

• Ruby on Rails (8.1): 빠른 개발 속도와 생산성, 테스트 친화성, API 구축에 충분한 성숙도.
• SQLite: 과제/로컬 환경에서 설정이 간단하고 재현성이 높음.
• Modular API design: STT → LLM → TTS를 분리하여 지연을 최소화하고 UX를 개선.
• SSE(LLM streaming): 사용자에게 즉시 피드백을 제공해 체감 지연을 줄임.
• Strict error contracts: 프론트에서 에러 코드 기반으로 UX를 분기하기 쉽게 설계.
• TTS prefetch: LLM 응답과 동시에 TTS를 비동기로 생성해 음성 대기 시간을 단축.
• English-only guardrails: 영어 입력만 허용하고(비영어 입력은 명확한 에러 코드 반환) 목표 사용 시나리오에 최적화.
• Input validation: 업로드 파일 크기/형식 검증으로 안정성 및 가용성 확보.

Tests & Verification

• Request specs

bin/rails test test/requests

• Full test suite

bin/rails test

• Manual API checks (Postman)
  • STT: POST /api/chat/stt
  • LLM stream: POST /api/chat/llm/stream
  • TTS: POST /api/chat/tts

Directory Structure

.
├── app/          # Rails app (controllers, models, services, views)
├── bin/          # Binstubs
├── config/       # Environment, routes, initializers
├── db/           # Migrations, seeds
├── docs/         # API/ERD docs
├── lib/          # Library code
├── log/          # Logs (ignored)
├── public/       # Static files
├── script/       # Scripts
├── storage/      # Active Storage
├── test/         # Tests
├── tmp/          # Temp files (ignored)
└── vendor/       # Vendor/bundled code

• Coding Agent 사용 내역은 docs 폴더 내에 있습니다.