Rinda 개발자 온보딩 가이드

수출 기업 매니저를 위한 AI 영업 자동화 플랫폼. 바이어 발굴 → 이메일 캠페인 → 답장 관리까지 자동화하는 풀스택 모노레포입니다. 이 문서 하나로 전체 아키텍처와 각 용어를 이해할 수 있습니다.

빠른 시작

사전 요구사항: Node 20+, Bun 1.2+, Yarn 4 (corepack), Docker, just (작업 러너).

git clone git@github.com:FINGU-GRINDA/send-grid-test.git
cd send-grid-test

just setup     # 사전검증 + .env 생성 + Docker(PG18+Redis8) + 의존성 설치 + 스키마 push
just seed      # 시드 데이터 생성
just dev       # admin: http://localhost:5173  /  API: http://localhost:3001

모노레포 구조

기술 스택

SSOT 원칙 (Single Source of Truth)

같은 데이터는 한 곳에만 정의합니다. 중복되면 drift(불일치)가 생깁니다. 프론트는 백엔드의 미러이며 자체 SSOT를 만들지 않습니다.

백엔드 · 3-Layer 아키텍처

모든 요청은 세 계층을 순서대로 통과합니다. 각 계층은 하나의 책임만 가집니다.

대표 흐름 예시 — 시퀀스 검색

// 1) routes/sequences.routes.ts  — 요청 파싱 + 서비스 위임 + ok() 응답
.get("/search", async ({ query, workspace }) => {
  const { items, cursor } = await listSequencesPaged({ ...filters })
  return ok({ items, cursor })            // utils/reply.ts 헬퍼
}, { workspaceAuth: true })               // ← 인증 매크로 (필수 선언)

// 2) services/sequence-read.service.ts  — DB 직접 접근
// 3) db/schema/sequences.ts             — 테이블 스키마

백엔드 · 인증 매크로

모든 라우트는 반드시 인증 매크로를 인라인 선언해야 합니다. 정적 게이트(check:route-auth)가 유일한 방어선이며, 런타임은 미선언 시 fail-open(public)이 됩니다. SSOT: plugins/auth.macro.ts

백엔드 · DB · Drizzle

PostgreSQL 18 + Drizzle ORM. 스키마는 elysia-server/src/db/schema/, 마이그레이션은 drizzle/*.sql.

마이그레이션 워크플로

// 1) src/db/schema/*.ts 편집
// 2) 마이그레이션 자동 생성 (손으로 쓰지 말 것!)
bun db:generate     // → 0NNN_*.sql + meta/0NNN_snapshot.json + _journal.json
// 3) 세 파일 함께 git add (하나라도 빠지면 게이트 실패)
git add drizzle/
// 4) 무결성 검증 (husky pre-commit + CI 에서 자동)
bun check:migrations   // F1~F8 실패모드 차단

백엔드 · 큐 · 워커 (BullMQ)

오래 걸리는 작업은 API에서 직접 처리하지 않고 BullMQ 큐에 넣습니다. 워커는 별도 Bun 프로세스로 독립 배포됩니다.

대표 큐

• SEQUENCE_EMAIL — 시퀀스 이메일 발송 / SEQUENCE_EMAIL_LOADER — DB pending → BullMQ delayed 적재(30초 틱)
• LEAD_DISCOVERY_SEARCH / _ANALYZE — 리드 발굴 검색·분석
• BUYER_SEARCH_MASTRA — 바이어 탐색 AI 파이프라인 / AGENT_MISSION — AI 에이전트 실행

백엔드 · 실시간 진행률 (SSE)

장시간 잡(시퀀스 발송, 리드 발굴)의 진행률은 SSE + Redis Pub/Sub로 실시간 전송. SSOT는 항상 DB. 위치: lib/sse/

백엔드 · AI 통합

기본 모델은 gemini-3-flash-preview. 스테이지별 모델 설정 SSOT: services/agent-model-settings.service.ts

모델 설정 아키텍처

• AGENT_MODEL_CATALOG — 코드 기본값 (SSOT)
• db.agentModelSettings — 어드민 오버라이드 (없으면 기본값)
• resolveAgentModel(key) — 60초 TTL 캐시 조회, fail-open. 어드민 변경 시 즉시 캐시 무효화

프론트엔드 · 디렉토리 구조

프론트엔드 · 상태관리

두 가지 상태를 명확히 구분합니다. 잘못 쓰면 stale 캐시 보안 위험 또는 과도한 동기화 비용이 발생합니다.

useQuery({ queryKey:["leads",p],
  queryFn:()=>leadsApi.search(p),
  staleTime:120_000 })

const wsAtom =
  atomWithStorage("selectedWorkspace",null)
const [ws,setWs] = useAtom(wsAtom)

프론트엔드 · API 레이어 (3계층)

프론트엔드 · 인증 · 권한

프론트엔드 · 디자인 시스템

SSOT는 admin/.claude/rules/frontend-design.md (희주님 관리 문서, 무단 수정 금지).

• 색상 토큰: 배경 bg-rd-n-200, 카드 bg-rd-n-white, 제목 text-rd-n-900, 액센트 text-rd-blue-500
• 타이포: 최소 text-xs(12px) 이상. 한글은 break-keep + [overflow-wrap:anywhere] 조합 필수
• 아이콘: Material Symbols Rounded → @/components/ui/material-symbol wrapper (lucide 직접 import 금지)
• i18n: 모든 사용자 노출 텍스트는 t() 키, 4개 언어(ko/en/id/ja) 모두 작성
• 라우팅: 신규 페이지는 router/lazy-imports.ts에 lazy import 등록 (번들 분할)

주요 도메인 기능

CI / 배포

send-ci.sh — 통합 검증

sh send-ci.sh            # full (기본, quiet) — lint + type-check + build
sh send-ci.sh fast       # pre-commit용 (빠름)
sh send-ci.sh full --verbose   # 전체 스트리밍 (디버깅)
sh send-ci.sh auth --fix # 라우트 권한 맵 + FE IAM 자동보정

환경 & 배포 파이프라인

E2E 테스트 (헥사고날)

Playwright + 헥사고날 포트/어댑터 패턴. 셀렉터 SSOT는 어댑터 1곳뿐이라 디자인 변경 시 어댑터만 수정하면 모든 spec이 따라옵니다.

cd e2e
npm run bootstrap        # 의존성 + storageState 준비
npm run test:local       # 로컬 (just dev 선행 필요)
npm run test:local:ui    # UI 모드 (브라우저 시각화)

시크릿 (Infisical)

환경변수는 코드/.env에 하드코딩하지 않고 Infisical로 관리합니다. 환경: local · alpha · beta.

infisical login
infisical run -e local -- sh send-ci.sh
infisical export -e local -f .env > elysia-server/.env

# Claude Code 스킬 (자연어)
/infisical add GEMINI_API_KEY sk-...
/infisical sync

용어 사전

첫 주 체크리스트