[AI 프로젝트 #0] 초기 세팅 #1: Node, Python, Vite 기반 모노레포 환경 설명

---

환경 설정

1. 사용 버전

• Node.js: v22.17.1
• Python: 3.13.7

Python은 가상환경(venv)을 사용해 프로젝트별 독립 환경을 구성할 예정이고, Node.js는 Vite + React 기반 프론트엔드 빌드

2. 프로젝트 구조 설계

모노레포(Monorepo) 방식을 채택하여 AI 모듈을 독립된 앱으로 구성하고, 공통 패키지를 공유하여 유지보수성을 높일 예정

ai-projects/
 ├─ frontend/                 # 프론트엔드 (Turborepo 관리)
 │   ├─ apps/                 # 개별 프론트엔드 프로젝트
 │   │   ├─ pdf/              # PDF 전용 프론트 (/pdf)
 │   │   └─ ...
 │   ├─ packages/             # 공통 패키지
 │   │   ├─ ui/               # 공용 UI 컴포넌트
 │   │   ├─ styles/           # CSS/Emotion 테마 최소화
 │   │   └─ utils/            # 공용 유틸 함수
 │   ├─ turbo.json            # Turborepo 파이프라인 설정
 │   └─ package.json          # Monorepo 의존성 관리
 │
 ├─ backend/                  # 백엔드 (Python MCP 서버)
 │   ├─ pdf_server/           # PDF RAG 서버
 │   └─ ...
 │
 └─ README.md                 # 전체 프로젝트 개요

3. 개발 환경: 모듈별 독립 실행

개발 단계에서는 각 모듈을 독립 서버로 실행

• frontend/apps/pdf → Vite Dev 서버 (5173)
• backend/pdf_server → FastMCP 서버 (5000)

👉 모듈별로 개발/테스트를 분리 가능 하며, turbo run dev 명령으로 동시에 실행 가능

4. 빌드 & 배포 환경: 모듈 단위 분리

프론트엔드

• npm run build → 각 앱은 /dist 산출물 생성
• 원하는 앱별 dist 파일을 서버에 올려 배포 가능

백엔드

• 원하는 모듈 서버만 Dockerize 진행
• PDF 전용 → backend/pdf_server 만

5. 공통 패키지 활용

중복을 최소화 하기 위해 공통 요소는 packages/에서 관

• ui: 버튼, 카드, 레이아웃 등 재사용 컴포넌트
• styles: 전역 테마 (다크모드, 글꼴 등)
• utils: API 호출, 인증 로직

👉 packages/에서 변경 시 모든 앱 반영이 가능

 

6. 실행 예시

Turborepo 실행

// turbo.json
{
  "pipeline": {
    "dev": {
      "dependsOn": ["^dev"],
      "cache": false
    },
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

• turbo run dev --filter=apps/pdf → PDF 앱만 실행

Docker 배포 예시

# docker-compose.yml
services:
  pdf_front:
    build: ./frontend/apps/pdf
    ports:
      - "5173:80"
  pdf_server:
    build: ./backend/pdf_server
    ports:
      - "5000:5000"