MAKITT Project Overview

MAKITT는 K-뷰티 브랜드의 글로벌 D2C 커머스를 위한 AI 네이티브 이커머스 플랫폼이다. 셀러가 스토어를 만들고, 상품을 등록하고, 주문을 처리하고, 전 세계에 배송하는 전 과정을 하나의 플랫폼에서 해결한다.

세 가지 Value Proposition을 기반으로 한다.

---

1. AI NATIVE

AI는 MAKITT에 추가된 기능이 아니다. 플랫폼 경험 전체를 구동하는 엔진이다.

AI 온보딩

셀러가 처음 가입하면 3D 지구본(Three.js) 위에서 대화형 온보딩이 시작된다. 판매 국가를 선택하고, 사업 유형을 고르고, 브랜드에 대해 자연어로 이야기하면 AI가 추가 질문을 던지며 스토어를 자동으로 구성한다.

판매 국가 선택 → 사업 유형 → 브랜드 설정 → AI 질의응답 → 자동 생성 → 결과 프리뷰

12개 특화 AI 에이전트

LangGraph 기반으로 커머스 도메인별 전문 에이전트를 운영한다.

모델 폴백 체인: Claude Haiku → Gemini Flash → Claude Sonnet 이미지 생성: Gemini Flash Image → Imagen 4.0

AI Drawer

웹앱 내 사이드 드로어 형태의 실시간 AI 채팅 인터페이스. WebSocket(socket.io)으로 양방향 통신하며, 마크다운 렌더링과 코드 하이라이팅을 지원한다.

INFINITE CLAUDE

자율 AI 개발 에이전트 시스템. 사용자가 Epic과 Acceptance Criteria를 등록하면, Supervisor AI가 Claude Code 인스턴스를 원격 환경에서 관리하며 자율적으로 코드를 생성하고 PR을 만든다.

---

2. ONE STOP GLOBAL

하나의 대시보드에서 다국가 스토어를 운영한다. 현지화, 결제, 세금, 규제 대응을 플랫폼이 처리한다.

타겟 마켓

Phase 1: 한국 (KR), 미국 (US), 일본 (JP)

각 마켓은 ISO 표준 기반으로 관리된다.

• ISO 3166-1: 국가 코드
• ISO 639-1: 언어 코드
• ISO 4217: 통화 코드

콘텐츠 현지화

• 번역 상태 추적: Pending → Translated → Approved
• HCS 컴포넌트 단위 번역 (비주얼 빌더 콘텐츠)
• 커머스 데이터 번역 (상품, 컬렉션, 카테고리)
• AI 자동 번역 + CSV 외부 번역 워크플로우

자동 i18n 추론

고객 접속 시 자동으로 언어, 통화, 시간대, 날짜 포맷을 결정한다. 감지 우선순위: 고객 설정 → GeoIP(MaxMind) + Accept-Language → 샵 기본값

결제 (Dual PG)

3계층 모델: ProcessorType(PG) → ProviderType(결제 브랜드) → PaymentMethodType

국가별 규제 대응

셀러 등록:

• KR: 사업자등록번호 (국세청 API 검증), 통신판매업 신고, VAT 10%
• US: Tax ID (SSN/EIN), W-9 전자인증, 주별 Sales Tax (0%~10.25%)
• JP: 개인/법인 구분, 마이넘버/법인번호, 소비세 10% (식품 8%)

국제 배송:

• SKU 단위 국제 메타데이터: HS코드, 원산지, 영문 상품명, USD 가격, 중량/치수, 보관온도
• 소액면세 기준: KR $150, US $800, JP ¥10,000
• DDP/DDU 인코텀즈 지원
• 상업송장 자동 생성

체크아웃 현지화:

• 국가별 주소 형식 (KR: 5자리 우편번호, US: ZIP+4, JP: 7자리 우편번호 + 都道府県)
• KR 해외직구 시 개인통관고유부호 수집
• 세금 표시: KR/JP 포함가, US 별도 표시

K-뷰티 D2C 특화

12개 K-뷰티 브랜드(Biodance, d'Alba, ANUA, COSRX, Beauty of Joseon, Torriden, TIRTIR, CLUBCLIO, Medicube, Ma:nyo, SKIN1004, Round Lab) 심층 분석에서 도출한 표준 D2C 사이트맵과 컴포넌트 체계를 내장한다.

3축 상품 분류: Product Type × Skin Concern × Product Line K-뷰티 전용 컴포넌트: 성분 하이라이트, 텍스처 프리뷰, 루틴 추천, 피부 진단, 인증 뱃지

---

3. SEAMLESS LOGISTICS INTEGRATION

핵심 원칙: 셀러는 물류 시스템의 존재를 알 필요가 없다.

전통적인 이커머스 플랫폼에서 셀러는 택배사를 선택하고, 풀필먼트를 직접 관리하고, 재고를 수동으로 추적해야 한다. MAKITT는 이 모든 복잡성을 내부 풀필먼트 시스템(Argo) 뒤에 숨긴다.

아키텍처

MAKITT Platform (셀러 UI)
    │
    │ Internal API
    ▼
makitt-agent (통합 레이어)
    │
    │ REST API / Webhook / Kafka
    ▼
ARGO Fulfillment System (셀러에게 보이지 않음)

셀러가 보는 물류

6개 메뉴로 단순화된 물류 관리:

입고 프로세스

• 기존 방식: 5단계 수동 프로세스 (창고와 직접 상호작용)
• MAKITT: 2단계 (입고 요청 → 상품 발송). 셀러가 창고 시스템과 직접 상호작용하지 않는다

Argo 풀필먼트 시스템 (내부)

셀러에게 보이지 않는 완전한 3PL 시스템:

---

프로젝트 구성

저장소 구조

makitt-root/
│
├── makitt-client/              # 프론트엔드 모노레포 (pnpm + Turbo)
│   ├── apps/web/               # 셀러 대시보드 (Next.js 15, port 3000)
│   ├── apps/builder/           # 비주얼 페이지 빌더 (port 3001)
│   ├── apps/shop/              # 고객 스토어프론트 (port 3003)
│   ├── apps/compiler/          # HCS 컴파일 서버
│   ├── packages/ui/            # 공유 컴포넌트 라이브러리
│   ├── packages/shared-auth/   # 인증 공유 모듈
│   └── packages/dev-panel/     # 개발자 도구
│
├── makitt-server/              # 백엔드 (Spring Boot 3.5.7, Java 21)
│   ├── makitt-api/             # REST 컨트롤러, DTO
│   ├── makitt-application/     # 비즈니스 로직
│   └── makitt-core/            # 도메인 엔티티, 레포지토리, VO
│
├── makitt-ai-agent/            # AI 에이전트 (FastAPI, LangGraph)
├── makitt-operator/            # 운영 서비스
├── makitt-infra-dev/           # 로컬 인프라 도구
│
├── argo/                       # 풀필먼트 시스템 (10개 서브 프로젝트)
│
├── apps/docs/                  # 문서 뷰어/에디터 (Next.js, port 3004)
├── docs/                       # 프로젝트 문서 (마크다운)
└── diagrams/                   # Mermaid 다이어그램

데이터 플로우

1. 셀러가 스토어 생성
   AI 온보딩 / 빌더 → makitt-client → makitt-server (DynamoDB)

2. 상품 등록
   makitt-server → Kafka (cms-sku-info-change) → Argo CMS

3. 고객 주문
   Shop 앱 → makitt-server (주문 생성) → Argo OMS (풀필먼트 위임)

4. 출고
   Argo OMS → WMS (피킹/패킹) → Sugar (배송) → 배송 추적 동기화

5. 반품
   고객 요청 → 셀러 승인 (MAKITT) → Argo (수거/입고/환불)

사용자 구조

User → Organization(s) → Shop(s)

• 셀러: 브랜드 오너/운영자. 셀러 대시보드와 빌더를 사용. JWT 인증
• 고객: 스토어프론트에서 구매. Cookie 기반 인증 (Email, Magic Link, Google, Kakao)
• 조직 역할: OWNER, ADMIN, MEMBER

노코드 빌더

• 62개 컴포넌트 타입 (레이아웃, 텍스트, 미디어, 인풋, 인터랙티브, 데이터, 유틸리티)
• 드래그 앤 드롭 (@dnd-kit)
• 디자인 토큰 시스템 (8개 카테고리: colors, spacing, fontSize 등)
• 데이터 바인딩: Mustache 문법 ({{product.name}}), 40+ 변환 함수
• 이벤트 시스템: 8개 트리거, 21+ 액션
• HCS 컴파일: TreeNode → HTML/CSS → LightningCSS → S3/CDN
• 샵 버전 관리: Draft → Published (롤백 지원)

기술 스택