AppHub 기술 스택 결정 과정
“최신 기술을 경험해보고 싶고, 세세하게 컨트롤할 수 있는 개발”이라는 핵심 동기에서 출발한 기술 선택 스토리다. 각 기술의 선택 근거와 고민 과정을 상세히 기록하고, 실제 구현에 필요한 아키텍처와 도구들을 정리한다. 프로젝트 기획과 비즈니스 로직은 2025-06-28-AppHub-개인-프로젝트-플랫폼-기획에서 다룬다.
시스템 아키텍처 개요
구현 중심 접근
비즈니스 요구사항과 사용자 경험은 2025-06-28-AppHub-개인-프로젝트-플랫폼-기획에서 정의했으므로, 여기서는 구체적인 기술 구현에 집중한다.
주요 컴포넌트 구성
| 레이어 | 컴포넌트 | 기술 스택 | 역할 |
|---|---|---|---|
| Frontend | Web Application | NextJS 14 + React + TypeScript | 사용자 인터페이스 |
| Frontend | UI Framework | ShadCN + Tailwind CSS | 컴포넌트 및 스타일링 |
| Frontend | State Management | Zustand + TanStack Query | 전역 상태 및 서버 상태 |
| Backend | AI Service | LangGraph Python + FastAPI | AI 로직 및 에이전트 |
| Backend | Web API | NextJS API Routes | 웹 애플리케이션 로직 |
| Database | Main DB | PostgreSQL (self-hosted) | 애플리케이션 데이터 저장 |
| Database | Vector Store | pgvector(우선) → Qdrant/Milvus(실험) | 벡터 임베딩 저장·검색 |
| Database | Cache | Redis | 세션 및 캐시 |
| Storage | Object Storage | MinIO (S3 호환) | 파일 및 이미지 |
| Analytics | Web Analytics | Google Analytics 4 | 사용자 행동 분석 |
| Support | Sponsorship | GitHub Sponsors | 후원 시스템 |
기술 선택 여정과 고민 과정
프로젝트 철학 설정
핵심 동기: “최신 기술을 경험해보고 싶고, 세세하게 컨트롤할 수 있는 개발을 하고 싶다”
이 프로젝트는 단순한 기능 구현보다는 다양한 최신 기술을 깊이 있게 경험하는 학습 플랫폼이다. 따라서 기술 선택에서도 안정성보다는 학습 가치와 확장 가능성을 우선시했다.
Frontend Stack 선택 스토리
NextJS 15를 선택한 진짜 이유
“SSR, CSR 등등의 다양한 렌더링 방식을 경험해보고 싶어서” + “최신 기술 경험”
다양한 렌더링 방식 경험 계획:
- SSR: 사용자 대시보드, SEO가 중요한 페이지
- CSR: AI 채팅 인터페이스, 실시간 상호작용
- SSG: 문서, 랜딩 페이지
- ISR: 프로젝트 갤러리, 동적 콘텐츠
React 19 + NextJS 15 최신 기능 경험:
- React 19의 새로운 훅들 (useOptimistic, useFormStatus)
- 개선된 서버 컴포넌트
- Turbopack의 향상된 개발 경험
- React Compiler 실험적 기능
React도 쓰고 싶어서
React 19의 최신 패턴들과 NextJS 15의 새로운 기능들을 실제 프로젝트에서 경험해보는 것이 목표다. 최신 기술 트렌드를 선경험하면서 포트폴리오 차별화도 노릴 수 있다.
ShadCN는 깔끔해서
표면적으로는 디자인이 깔끔해서 선택했지만, 실제로는 완전한 코드 소유권이 가장 큰 매력이었다. npm 패키지가 아닌 직접 코드 복사 방식이라 자유롭게 수정하고 확장할 수 있다.
AI Framework 선택의 고민
LangGraph vs AI SDK vs LangConnect 딜레마
“langgraph와 ai-sdk중에 조금 고민이 있었는데…”
AI SDK의 매력:
- React 최적화가 잘 되어있음 (useChat, useCompletion 등)
- 굳이 프레임워크를 나눌 필요 없는 장점
하지만 LangGraph를 선택한 이유:
- “langgraph가 더 세세하게 컨트롤이 가능해서”
- “내가 해보고 싶은걸 다 해보는 이 프로젝트의 취지에 더 잘 맞아”
복잡한 AI 워크플로우와 에이전트 구현에서 LangGraph의 세밀한 제어가 더 적합하다고 판단했다.
AI Framework 선택의 핵심
“세세하게 컨트롤이 가능한” LangGraph가 “해보고 싶은걸 다 해보는 프로젝트 취지”와 완벽하게 일치했다. AI SDK의 편의성보다는 학습 가치를 우선시한 결정이다.
LangConnect 도입 검토
초기 검토: LangConnect 적용 결정
LangChain 팀의 관리형 RAG API 서버인 LangConnect를 도입하면 개발 속도를 크게 끌어올릴 수 있다고 판단했다.
LangConnect의 AppHub 적용 이점:
| 영역 | 기존 계획 | LangConnect 적용 | 개선 효과 |
|---|---|---|---|
| RAG 인프라 | 수동 구현 | 즉시 사용 가능 | 개발 시간 70% 단축 |
| 벡터 DB | pgvector 직접 설정 | 내장 지원 | 설정 복잡도 대폭 감소 |
| API 설계 | REST API 설계 필요 | 표준 API 제공 | 구현 시간 단축 |
| 확장성 | 수동 스케일링 | 자동 최적화 | 운영 효율성 향상 |
LangConnect + LangGraph 하이브리드 아키텍처 (초기 설계):
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ NextJS App │◄──►│ LangConnect │◄──►│ LangGraph │
│ (Frontend) │ │ (RAG Service) │ │ (AI Agents) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Supabase │ │ PostgreSQL │ │ Redis Cache │
│ (Auth/Storage)│ │ + pgvector │ │ (Sessions) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
구체적 통합 방안(초기 설계):
-
LangConnect: 문서 관리 및 RAG 검색 담당
- 프로젝트 문서 인덱싱
- 사용자 질의에 대한 컨텍스트 검색
- 벡터 임베딩 자동 관리
-
LangGraph: AI 에이전트 및 워크플로우 담당
- 사용자 질의 분석 및 라우팅
- 복잡한 AI 워크플로우 실행
- 멀티 스텝 추론 및 의사결정
-
NextJS: 사용자 인터페이스 및 통합
- LangConnect API 호출
- LangGraph 에이전트 제어
- 실시간 스트리밍 응답
재검토 결과(갱신)
최종적으로는 LangConnect를 도입하지 않기로 결정. 학습 목적과 세밀 제어를 위해 RAG는
LangGraph Server + 자체 Vector Store로 구현한다.
- 도입하지 않는 이유: 프레임워크 단순화, 직접 운영 경험 축적, 서비스 간 오버헤드 감소
- 영향: 인덱싱/검색 API는 자체 구현 또는 LangChain VectorStore로 직접 연동
Python vs Node.js 선택의 현실적 고려
“굳이 웹이 typescript인데 파이썬을 선택한 이유는…”
1순위 이유: “가장 최신 기술은 파이썬으로 나오는게 가장 이유가 크고”
- LLM 관련 새로운 라이브러리와 기법들이 Python 우선 출시
- 기술 트렌드를 빠르게 따라갈 수 있음
2순위 이유: “나중에 일부 기능을 떼가서 했을때 협업 시 나도 아직 LLM을 파이썬을 다루는게 익숙한 사람이 더많은듯해”
- 향후 협업 시 AI 개발자들과의 호환성
- 팀 확장 시 인력 확보 용이성
언어 분리의 트레이드오프
TypeScript와 Python 분리로 인한 복잡도 증가는 감수하되, AI 생태계의 최신 기술 접근성과 협업 확장성을 우선시했다.
Database 선택의 실용적 접근
Supabase의 결정적 장점(기록용)
과거 검토 기록
“Supabase는 귀찮은 작업들을 쉽고 빠르게 구현” → 초기에는 개발 속도를 위해 유력 후보였다.
장점 요약:
- PostgreSQL + pgvector + authentication를 한 번에 해결
- 복잡한 설정 작업들을 대폭 단순화
- 개발 속도 향상에 실질적 도움
최종 결정(갱신)
Supabase는 사용하지 않음. 메인 DB는 자체 운영 PostgreSQL, 벡터 스토어는 실험 목적에 따라
pgvector/Qdrant/Milvus중 단계적으로 선택.
벡터 스토어 비교: pgvector vs Qdrant vs Milvus
“학습·세밀 제어 목적”을 최우선으로 하되, 확장성과 성능도 고려한다.
| 항목 | pgvector | Qdrant | Milvus |
|---|---|---|---|
| 포지션 | PostgreSQL 확장 | 벡터 DB(단일 서비스→수평 확장) | 분산 벡터 DB(대규모) |
| 인덱스 | IVF, HNSW | HNSW, PQ/압축 옵션 | HNSW, IVF, IVF_PQ, DiskANN 등 |
| 메타데이터 쿼리 | SQL 조인 강함 | 페이로드 필터 강함 | 필터/스키마 제공 |
| 운영 난이도 | 낮음(기존 PG 재사용) | 중간(Docker 단일로 시작 쉬움) | 높음(K8s/클러스터 권장) |
| 규모/성능 | ≤ 5–10M 벡터권, OLTP+벡터 혼합에 유리 | 중대규모·실시간 upsert/필터 | 100M+·고QPS·GPU·분산 |
선택 원칙
- 메인 RDBMS는 PostgreSQL로 일원화
- 벡터 스토어는 학습 목적에 따라 교체 가능하도록 추상화(
VectorStore 인터페이스)
최종 결정(1차 선택)
- 메인 DB: PostgreSQL (self-hosted)
- 벡터 스토어: pgvector로 시작 → Qdrant, Milvus 순차 실험 예정
참고 문서: pgvector, Qdrant Docs, Milvus Docs
인프라 선택의 현실과 계획
GCP 선택의 솔직한 이유
GCP 선택의 솔직한 이유
기술적 우수성보다는 무료로 사용할 수 있는 현실적 지원이 더 큰 결정 요인이었다. 하지만 이것도 나쁘지 않은 선택이다.
기술적 우수성보다는 현실적 제약이 더 컸다. 하지만 이것도 나쁘지 않은 선택:
- GCP 경험 축적 기회
- 향후 홈서버와 비교 학습 가능
도메인 전략
개인 브랜딩 계획
syshin0116.com (GoDaddy 구매 예정) - 저렴한 가격과 개인 브랜딩을 동시에 노린다.
단순한 비용 절약이 아니라 개인 브랜딩 구축과 프로젝트 완성에 대한 동기부여 차원이다.
Database & Infrastructure
Database 선택: Supabase vs 대안
| 기능 | Supabase | 직접 구축 |
|---|---|---|
| PostgreSQL + 벡터 | 통합 제공 | Postgres 설치 + pgvector/Qdrant/Milvus 선택 |
| Authentication | 내장 | NextAuth/Auth.js 등 직접 구성 |
| 실시간 동기화 | 내장 | 필요 시 별도 구성(WebSocket/Redis) |
| 파일 스토리지 | 내장 | MinIO/S3 등 별도 서비스 |
| 설정 복잡도 | 낮음 | 높음 |
| 개발 속도 | 빠름 | 느림 |
선택(갱신): 직접 구축 (PostgreSQL self-hosted + 벡터 스토어 교체 실험)
벡터 스토어 운영 계획:
- 현재: pgvector로 시작(개발 단순성, SQL 통합)
- 이후: Qdrant, Milvus 순차 실험(성능·확장성 비교)
배포 인프라
GCP 선택 배경
- 지원 가능한 분이 있어서 우선 선택
- 추후 홈서버로 마이그레이션 계획
- 도메인: syshin0116.com (GoDaddy에서 구매 예정)
모니터링 & 분석
분석 도구 비교
| 도구 | 비용 | 모바일 앱 | 기능 범위 | 설정 복잡도 | 데이터 소유권 | 추천도 |
|---|---|---|---|---|---|---|
| Google Analytics 4 | 무료 (월 1천만 히트) | 있음 | 매우 높음 | 중간 | Google 소유 | ⭐⭐⭐⭐⭐ |
| Umami | 무료 (셀프호스팅) | 없음 | 중간 | 높음 | 완전 소유 | ⭐⭐⭐ |
| PostHog | 무료 (월 1백만 이벤트) | 웹앱 | 높음 | 중간 | 제한적 | ⭐⭐⭐⭐ |
| Plausible | 유료 ($9/월) | 없음 | 중간 | 낮음 | 제한적 | ⭐⭐⭐ |
선택: Google Analytics 4 + 추후 홈서버에서 Umami 실험
후원 시스템 비교
| 플랫폼 | 수수료 | 설정 복잡도 | 결제 방식 | 개발자 친화도 | 추천도 |
|---|---|---|---|---|---|
| GitHub Sponsors | 0% | 낮음 | 월간/일회성 | 매우 높음 | ⭐⭐⭐⭐⭐ |
| Buy Me a Coffee | 5% | 매우 낮음 | 일회성 주로 | 중간 | ⭐⭐⭐ |
| Ko-fi | 0% (무료 플랜) | 낮음 | 월간/일회성 | 중간 | ⭐⭐⭐⭐ |
| Polar | 4% + 40¢ | 중간 | 구독/일회성 | 높음 | ⭐⭐⭐ |
선택: GitHub Sponsors (무료, 개발자 친화적)
기술 스택 상세 비교
최종 선택된 기술 스택
| 컴포넌트 | 선택된 기술 | 버전 | 선택 이유 |
|---|---|---|---|
| 웹 프레임워크 | NextJS | 15 (최신) | 다양한 렌더링 + React 19 최신 기능 |
| UI 라이브러리 | React | 19 | 최신 훅과 서버 컴포넌트 경험 |
| AI 프레임워크 | LangGraph | Python | 세밀한 제어 + 최신 AI 기술 |
| 데이터베이스 | Supabase | PostgreSQL + pgvector | 통합 솔루션 + 빠른 개발 |
AI Framework 최종 비교표
| 항목 | LangGraph Python | Vercel AI SDK | 선택 근거 |
|---|---|---|---|
| 세밀한 제어 | 매우 높음 | 중간 | 프로젝트 취지에 핵심 |
| React 최적화 | 보통 | 매우 높음 | 편의성보다 학습 우선 |
| 최신 AI 기능 | 가장 빠름 | 빠름 | 기술 트렌드 추종 |
| 협업 친화도 | 높음 | 중간 | 향후 확장성 고려 |
| 개발 복잡도 | 높음 | 낮음 | 학습 가치 우선 |
Python vs Node.js 비교표
| 항목 | Python 버전 | Node.js 버전 | 결정 요인 |
|---|---|---|---|
| 최신 기술 접근 | 가장 빠름 | 늦음 | 핵심 선택 기준 |
| 언어 통일성 | 분리 | 통합 | 학습 경험 중시 |
| 협업 생태계 | 매우 큰 | 성장 중 | 미래 확장성 |
| 구현 복잡도 | API 분리 | 통합 | 복잡도 감수 |
통신 아키텍처
LangGraph ↔ NextJS 통합 방식
하이브리드 통신 구조
LangGraph CLI가 자동으로 FastAPI 서버를 생성하여 NextJS와 표준 HTTP/WebSocket으로 통신한다.
RESTful API + WebSocket 하이브리드 구조
실시간 스트리밍
| 방식 | 용도 | 장점 |
|---|---|---|
| WebSocket | 양방향 실시간 통신 | 즉시 응답, 상태 동기화 |
| Server-Sent Events | 서버→클라이언트 스트리밍 | AI 응답 실시간 표시 |
| 자동 재연결 | 연결 끊김 복구 | 안정성 보장 |
MCP 통합 계획
향후 Model Context Protocol 지원으로 Claude Desktop, Cursor 등 다양한 클라이언트에서 직접 접근 가능하도록 확장할 예정이다.
프로젝트 구조
Monorepo 구조
AppHub
├── apps/
│ ├── ai-service/ # Python LangGraph 서비스
│ │ ├── main.py
│ │ ├── pyproject.toml
│ │ ├── uv.lock
│ │ └── .venv/
│ └── web/ # Next.js + shadcn-ui 프론트엔드
│ ├── app/
│ ├── components/
│ ├── package.json
│ └── ...
├── packages/
│ ├── eslint-config/ # 공유 ESLint 설정
│ ├── typescript-config/ # 공유 TypeScript 설정
│ └── ui/ # shadcn-ui 컴포넌트
├── docs/ # 프로젝트 문서
├── README.md
├── package.json # 루트 package.json
├── pnpm-workspace.yaml # pnpm workspace 설정
└── turbo.json # Turborepo 설정
환경별 설정
컨테이너 기반 개발 환경
Docker vs Podman 선택
초기에는 Podman을 고려했으나, 개발 생산성과 환경 이동성을 고려하여 Docker + Docker Compose를 최종 선택했다.
개발 환경 구성:
- NextJS 개발 서버 (포트 3000)
- LangGraph AI 서비스 (포트 8000)
- PostgreSQL(메인) + pgvector/Qdrant/Milvus(중 택1)
- Redis 캐시 서버
- Traefik 리버스 프록시 (Nginx 대신 선택)
배포 전략
멀티 환경 배포 전략
환경 이동성 최우선
로컬 → GCP → RunPod → 홈서버 등 다양한 환경에서 동일하게 동작해야 하므로 컨테이너 기반 아키텍처가 필수다.
Phase 1: GCP Compute Engine
| 항목 | 세부사항 | 선택 근거 |
|---|---|---|
| 인프라 | Compute Engine + Docker Compose | Cloud Run보다 컨테이너 제어 자유도 높음 |
| 프록시 | Traefik (Nginx 대신) | 자동 SSL, Docker 통합, 설정 간소화 |
| 예상 비용 | 10-20 | Load Balancer 사용 안 함으로 절약 |
| 장점 | 홈서버 연습 환경, 완전한 제어 | 학습 효과 극대화 |
Load Balancer 제외 이유
Google Cloud Load Balancer는 월 $18+ 비용으로 개인 프로젝트에는 과도하다. 대신 Traefik으로 프록시 + SSL 자동화를 구현한다.
Phase 2: 홈서버 마이그레이션
| 항목 | 세부사항 | 기대 효과 |
|---|---|---|
| 하드웨어 | Mini PC (Intel N100), 16GB RAM, 1TB NVMe | 완전한 데이터 제어 |
| 이동성 | Docker Compose 파일 그대로 이전 | 환경 차이 최소화 |
| 예상 비용 | 초기 25 | 장기적 비용 절약 |
| 학습 가치 | 풀스택 인프라 관리 경험 | 포트폴리오 차별화 |
도메인 및 SSL 전략
도메인 계획
syshin0116.com (GoDaddy 구매 예정) - 저렴한 가격과 개인 브랜딩을 동시에!
보안 및 인증
인증 재결정: NextAuth(Auth.js) + PostgreSQL
- 세션/계정 저장소: Postgres(Prisma Adapter)
- 프로바이더: GitHub/Google 등 OAuth + Email OTP(선택)
- 라우팅 보호: NextJS Middleware로 보호 라우트 구성
- 서버-투-서버 보안: NextJS API → LangGraph Server 간 JWT/헤더 기반 검증
모니터링 및 후원 시스템 구현
Google Analytics 4 통합
- 페이지뷰 트래킹: 자동 경로 변경 감지
- 이벤트 트래킹: 사용자 상호작용 분석
- NextJS Script 컴포넌트: 최적화된 스크립트 로딩
GitHub Sponsors 통합
- 후원 버튼: 고정 위치 후원 링크
- GitHub 연동: 0% 수수료 후원 시스템
- 반응형 디자인: 모바일 친화적 UI
리버스 프록시 선택: Traefik
Nginx vs Traefik 결정 과정
최종 선택: Traefik (무료 버전)
유료 서비스 없이 Nginx보다 뛰어난 자동화와 편의성을 제공한다.
| 기능 | Nginx | Traefik CE (무료) | 승자 |
|---|---|---|---|
| 설정 복잡도 | 높음 (수동 설정) | 낮음 (라벨 기반) | 🏆 Traefik |
| SSL 자동화 | 수동 (Certbot) | 완전 자동 | 🏆 Traefik |
| Docker 통합 | 제한적 | 네이티브 지원 | 🏆 Traefik |
| 모니터링 | 별도 도구 필요 | 내장 대시보드 | 🏆 Traefik |
| 비용 | 완전 무료 | 완전 무료 | 🤝 동일 |
Traefik 선택 이유
- 라벨 2줄로 새 서비스 추가 가능
- Let’s Encrypt SSL 완전 자동화
- 실시간 웹 대시보드 제공
- Docker Compose와 완벽 통합
성능 최적화
NextJS 15 최적화 전략
최신 기능 활용
- Turbopack: 개발 서버 속도 대폭 향상
- React 19 Server Components: 클라이언트 번들 크기 최소화
- 자동 이미지 최적화: WebP, AVIF 형식 자동 변환
LangGraph 최적화 계획
- 체크포인트 설정: 30일 TTL로 세션 관리
- 벡터 임베딩: OpenAI 텍스트 임베딩 활용
- 의존성 최적화: 필요한 패키지만 설치
개발 워크플로우
컨테이너 기반 개발 환경
원클릭 개발 환경
# 전체 환경 시작 docker-compose up -d # 로그 실시간 확인 docker-compose logs -f # 개별 서비스 재시작 docker-compose restart nextjs
환경 구성:
- Docker + Docker Compose (Podman 대신 선택)
- Traefik 대시보드 (http://localhost:8080)
- 핫 리로드 지원 (코드 변경시 자동 반영)
CI/CD 및 품질 관리
- GitHub Actions: 자동 테스트 및 배포
- ESLint + Prettier: 코드 품질 자동 검사
- TypeScript: 정적 타입 검사
관련 문서
- 2025-06-28-AppHub-개인-프로젝트-플랫폼-기획 - 프로젝트 기획 및 비즈니스 로직
- 향후 추가 예정: 개발 환경 설정 가이드, 배포 매뉴얼