Ringle Assignment Monorepo

React + TypeScript + Vite 클라이언트와 Ruby on Rails API 서버를 포함하는 모노레포 프로젝트입니다.

구조

• apps/client - React + TypeScript + Vite + FSD 아키텍처
• apps/server - Ruby on Rails API

시작하기

Docker (추천) 🐳

# 전체 서비스 시작 (Client + Server)
docker-compose up

# 백그라운드 실행
docker-compose up -d

# 로그 보기
docker-compose logs -f

# 서비스 중지
docker-compose down

자세한 내용은 README.docker.md 참조

로컬 개발

사전 요구사항

• Client: bun, Node.js 20+
• Server: Ruby 3.3.0+, Rails 7.1.6+, SQLite3

설치

# bun 설치
curl -fsSL https://bun.sh/install | bash

# Ruby 3.3.0 + rbenv 설치
brew install rbenv
rbenv install 3.3.0
rbenv global 3.3.0

# 의존성 설치
bun install

# 서버 의존성
cd apps/server
bundle install

개발

# 클라이언트 시작 (http://localhost:3000)
bun run dev:client

# 서버 시작 (http://localhost:4000)
cd apps/server
bundle exec rails server -p 4000

아키텍처

Frontend (Client)

• Framework: React 19 + TypeScript
• Build Tool: Vite
• Architecture: Feature-Sliced Design (FSD)
• State Management: Zustand + TanStack Query
• Styling: Tailwind CSS
• Package Manager: bun
• Linting: Biome
• PWA: vite-plugin-pwa 지원
• AI Integration:
  • STT: Web Speech API (무료) / OpenAI Whisper
  • LLM: Groq ( llama-3.3-70b )
  • TTS: Web Speech API (무료)

Backend (Server)

• Framework: Ruby on Rails 7.1 (API Mode)
• Database: SQLite3
• Package Manager: bundler
• Authentication: JWT + bcrypt
• Testing: RSpec

기능

1. AI 튜터링 시스템

• 음성 대화: AI 튜터와 실시간 음성 대화
• STT: Web Speech API (무료) 또는 OpenAI Whisper
• LLM: Groq API ( llama-3.3-70b )
• TTS: Web Speech API (무료)
• VAD: Web Audio API 기반 음성 감지

2. 멤버십 시스템

• 멤버십 플랜: 다양한 기능 조합 (학습, 대화, 분석)
• 결제 시스템: Mock PG 연동
• 권한 관리: 기능별 접근 제어

3. 오디오 기능

• Waveform 시각화: wavesurfer.js
• 실시간 볼륨 모니터링
• 오디오 녹음: MediaRecorder API
• 무음 제거: VAD 기반

스크립트

Root (Monorepo)

bun run dev:client    # 클라이언트 개발 서버 시작
bun run dev:server   # 서버 개발 서버 시작
bun run build        # 모든 앱 빌드
bun run test         # 모든 테스트 실행
bun run lint         # 모든 앱 린트

Client (apps/client)

bun run dev          # 개발 서버
bun run build        # 프로덕션 빌드
bun run type-check   # 타입 체크
bun run format       # 코드 포맷 (Biome)
bun run check        # 린트 + 타입 체크
bun run test         # 테스트 (Vitest)

Server (apps/server)

bundle exec rails server -p 4000    # 서버 시작
bundle exec rails db:create         # DB 생성
bundle exec rspec                   # 테스트 실행
bundle exec rubocop                 # Ruby 린트

환경 변수

Client (apps/client/.env)

VITE_API_URL=http://localhost:4000/api
VITE_GROQ_API_KEY=your_groq_api_key

Server (apps/server/.env)

RAILS_ENV=development
JWT_SECRET=your_jwt_secret_here

CI/CD

• Client CI: apps/client/** 변경 시 자동 실행 (client-ci.yml)
  • Biome lint + type check
  • Vitest tests
  • Vite build
• Server CI: apps/server/** 변경 시 자동 실행 (server-ci.yml)
  • RuboCop lint
  • Brakeman security scan
  • Bundler audit
  • RSpec tests

테스트

Client

cd apps/client
bun run test          # Vitest로 테스트 실행
bun run test:ui       # 테스트 UI 열기

Server

cd apps/server
bundle exec rspec                    # 전체 테스트
bundle exec rspec spec/models/      # 모델 테스트만
bundle exec rspec spec/requests/    # 요청 테스트만

문서

• CLAUDE.md - 프로젝트 개발 가이드
• .claude/Agent.md - AI 에이전트 사용 가이드
• README.docker.md - Docker 사용 가이드

기술 스택

구분	기술
Frontend	React 19, TypeScript, Vite, Zustand, TanStack Query, Tailwind CSS, Biome
Backend	Ruby 3.3, Rails 7.1, SQLite3, JWT, RSpec
AI	Groq (LLM), Web Speech API (STT/TTS)
DevOps	Docker, GitHub Actions

설계 및 기술 스택 선정 배경

🏗️ 모노레포 선택 (Bun Workspaces)

• 이유: 클라이언트와 서버를 하나의 저장소에서 관리하여 개발 경험 일관성 유지
• 장점: 공통 스크립트 실행, 의존성 통합 관리, CI/CD 파이프라인 단순화
• 대안: Turbo Repo, Nx도 고려했으나 bun workspaces가 경량이면서도 충분히 기능적임

🎨 Frontend 아키텍처 (FSD - Feature-Sliced Design)

• 이유: 대규모 React 프로젝트의 유지보수를 위해 엄격한 레이어 의존성 규칙이 필요했음
• 선택: pages → widgets → features → entities → shared 순서의 레이어 구조
• 장점: 코드 재사용성 향상, 테스트 용이, 팀 협업 시 일관된 코드 구조 유지

🧠 AI 서비스 선택

• STT (Speech-to-Text):
  • 기본: Web Speech API (무료, 브라우저 내장) - 개발/테스트용
  • 유료: OpenAI Whisper - 프로덕션 품질 필요 시
• LLM: Groq (llama-3.3-70b) - 무료 티어 사용 가능, 빠른 응답 속도
• TTS: Web Speech API (무료) - 브라우저 내장 음성 합성

🗄️ 데이터베이스 (SQLite3)

• 이유: 학습용 프로젝트로 복잡한 쿼리나 대규모 동시접속이 필요 없음
• 장점: 설정 간단, 개발 환경 구축 용이, 파일 기반이라 백업 단순

🔐 인증 (JWT)

• 이유: stateless API 서버에 적합, 확장성 확보
• 보안: bcrypt로 비밀번호 해시화, JWTsecret 환경변수 관리

🧪 테스트 전략

• Client: Vitest + React Testing Library - 컴포넌트 단위 테스트
• Server: RSpec - 모델/컨트롤러 테스트
• CI: 각 앱 변경 시 자동으로 테스트 실행

🐳 Docker

• 이유: 개발 환경 일관성 보장 (팀원 모두 동일한 환경)
• 구성: client (Bun + Node), server (Ruby 3.3 + Rails) 분리 컨테이너

AI 개발 도구

이 프로젝트는 AI 협업으로 개발되었습니다:

AI	역할	모델
Claude Code	주요 코드 작성, 아키텍처 설계, 디버깅	Opus 4.6
Claude Sonnet	코드 리뷰, 최적화 제안, 테스트 작성	Sonnet 4.6
Zai (中国企业)	중국어 문서화, 로컬라이징 지원	-

Claude Code와 Sonnet은 Anthropic에서 개발한 AI 어시스턴트입니다.