Rapida voice-ai 딥다이브
— 전화 한 통을 STT·TTS·VAD·LLM 14종 공급자로 오케스트레이션하는 오픈소스 음성 에이전트 플랫폼

이벤트 기반 아키텍처를 Go 인터페이스로 실전 구현

패킷 하나가 ContextId()·PacketName() 두 메서드만 요구하는 얇은 인터페이스라는 점이 핵심이다. 새 이벤트 타입을 추가해도 기존 라우팅 코드는 건드릴 필요가 없다(개방-폐쇄 원칙). api/assistant-api/internal/type/packet.go를 정독하면 "실무에서 이벤트 이름을 어떻게 짓는가"(커맨드=동사, 이벤트=과거형)까지 배울 수 있다.

팩토리 패턴으로 20개 넘는 외부 API를 갈아 끼우기

transformer.go·vad.go·end_of_speech.go 세 파일 모두 같은 뼈대를 쓴다 — 옵션 구조체 + 함수형 옵션(functional options) + switch 팩토리. 아래는 VAD 팩토리를 단순화한 형태다.

// 함수형 옵션 패턴: New(옵션...) 형태로 유연하게 구성
func New(opts ...Option) (internal_type.VoiceActivityDetectorExecutor, error) {
    options := &options{ctx: context.Background()}
    for _, opt := range opts {
        opt(options)
    }
    provider, _ := options.options.GetString("microphone.vad.provider")
    switch VADIdentifier(provider) {
    case FIRERED_VAD:
        return internal_vad_firered.New(...)
    case TEN_VAD:
        return internal_vad_ten.New(...)
    case SILERO_VAD:
        return internal_vad_silero.New(...)
    default:
        return internal_vad_silero.New(...) // 기본값도 명시적으로 정함
    }
}

단계별 파이프라인 상태를 구조체로 강제하기

channel/pipeline/types.go의 각 파이프라인 구조체(CallReceivedPipeline 등)는 자체 Validate() bool을 갖고 있다. 통화 처리 도중 "이 단계에 필요한 값이 비어 있다"는 사고를 컴파일 타임이 아니라 런타임 초입에서 빠르게 잡아낸다 — 상태 기계(state machine)를 타입으로 표현하는 실전 예제.

전화망 프로토콜 6종을 한 코드베이스에서

channel/telephony/internal/ 밑에 asterisk·exotel·sip·telnyx·twilio·vonage가 각자 폴더를 갖고 있고, 순수 SIP는 sip/에 자체 SIP 스택(inbound/outbound/registration/middleware)까지 구현돼 있다. 전화 시스템(SIP·RTP·오디오 코덱 G.711)을 실무 코드로 배우기 좋은 자료다.

관측가능성(Observability)을 나중에 붙이지 말고 처음부터 1급 개체로

observability.Recorder는 RecordEvent·RecordLog·RecordWebhook·RecordMetadata 같은 구조화된 레코드 타입을 받아, 등록된 여러 collectors(요청 로그·툴 로그·webhook·telemetry·billing 등)로 팬아웃한다. "일단 기능부터 만들고 로그는 나중에"가 아니라, 파이프라인 설계 단계부터 관측을 끼워 넣은 구조를 볼 수 있다.

모노레포에서 언어를 섞어 쓰는 기준

Go(성능이 중요한 실시간 오디오/네트워크)·Python(document-api, RAG·임베딩 생태계가 Python에 풍부)·TypeScript(관리 콘솔 UI)로 역할을 명확히 나눴다. "왜 이 서비스는 이 언어로 짰을까"를 각 서비스의 책임과 대조해보면 언어 선택 기준을 배울 수 있다.

실습 아이디어: api/assistant-api/internal/vad/vad.go의 팩토리 패턴을 복사해, 내가 좋아하는 언어로 "가짜 STT 공급자 3개를 설정 값으로 스위칭하는" 미니 스켈레톤을 만들어 보라.

Docker Compose로 전체 플랫폼 로컬 기동 난이도 ★☆☆ 입문

git clone → make setup-local && make build-all → make up-all 순서로 실행하고, http://localhost:3000에서 관리 콘솔이 뜨는지 확인한다. docker compose ps로 어떤 서비스가 몇 개 컨테이너로 떴는지 살펴보라. 목표: 4개 API + DB + 캐시 + UI가 실제로 몇 개의 프로세스로 나뉘는지 눈으로 확인.

공급자 자격증명 없이 STT/TTS 팩토리 코드만 추적 난이도 ★☆☆ 입문

API 키가 없어도 코드는 읽을 수 있다. transformer.go의 GetTextToSpeechTransformer()를 열어 지원 공급자 14개를 나열해보고, 그중 하나(예: internal_transformer_deepgram 폴더)를 열어 실제 HTTP/WebSocket 호출이 어디서 일어나는지 찾는다. 목표: "설정 문자열 하나가 실제 코드의 어느 지점으로 연결되는지" 추적하는 연습.

패킷 흐름에 로그 한 줄 심어 관찰하기 난이도 ★★☆ 중급

로컬에서 assistant-api를 빌드해 실행하고(go build -o bin/assistant ./cmd/assistant), adapters/internal/dispatch.go의 dispatch() 함수에 log.Printf("packet: %s", p.PacketName()) 한 줄을 추가해본다. 텍스트 기반 endpoint-api로 간단한 요청을 보내며 어떤 순서로 패킷이 찍히는지 관찰한다. 목표: §4에서 설명한 8단계 흐름이 실제 로그에서도 그대로 보이는지 검증.

새 VAD 공급자를 "가짜"로 하나 추가해보기 난이도 ★★★ 고급

api/assistant-api/internal/vad/internal/silero_vad/ 폴더 구조를 참고해, 실제 모델 없이 "3초에 한 번씩 무조건 말했다고 판정하는" 더미 VAD 구현체를 만들고 vad.go의 switch문에 새 케이스로 등록해본다. .claude/skills/vad-integration/ 스킬 문서를 함께 참고하면 이 레포가 정의한 "정석 추가 절차"를 그대로 따라갈 수 있다. 목표: 팩토리 확장점을 손으로 직접 넓혀보기.

SIP 트렁크로 순수 SIP 통화 흐름 재현 난이도 ★★★ 고급

api/assistant-api/sip/의 inbound/outbound/registration 코드를 읽고, 무료 SIP 트렁크 테스트 서비스(또는 로컬 Asterisk/FreeSWITCH)로 실제 통화를 한 번 걸어본다. sip/testdata/freeswitch/에 테스트용 설정 예시가 있다. 목표: 전화망 신호(SIP INVITE 등)가 어떻게 Rapida 내부 이벤트로 번역되는지 끝까지 추적.