AppHub 구조 및 기술 스택

AppHub 기술 스택 결정 과정

“최신 기술을 경험해보고 싶고, 세세하게 컨트롤할 수 있는 개발”이라는 핵심 동기에서 출발한 기술 선택 스토리다. 2025년 10월 기준 최신 도구들과 프레임워크를 반영하여, 각 기술의 선택 근거와 고민 과정을 상세히 기록하고, 실제 구현에 필요한 아키텍처와 도구들을 정리한다. 프로젝트 기획과 비즈니스 로직은 2025-10-06-AppHub-개인-프로젝트-플랫폼-기획에서 다룬다.

시스템 아키텍처 개요

구현 중심 접근

비즈니스 요구사항과 사용자 경험은 2025-10-06-AppHub-개인-프로젝트-플랫폼-기획에서 정의했으므로, 여기서는 구체적인 기술 구현에 집중한다.

주요 컴포넌트 구성

레이어	컴포넌트	기술 스택	역할
Frontend	Web Application	NextJS 15 + React 19 + TypeScript 5.x	사용자 인터페이스
Frontend	UI Framework	ShadCN + Tailwind CSS	기본 컴포넌트 및 스타일링
Frontend	AI UI Components	prompt-kit	AI 챗봇 인터페이스 (PromptInput, Message, CodeBlock 등)
Frontend	State Management	Zustand / Jotai (검토 중) + TanStack Query	전역 상태 및 서버 상태
Backend	AI Service	LangGraph Python + FastAPI	AI 로직 및 에이전트
Backend	Web API	NextJS API Routes	웹 애플리케이션 로직
Database	Main DB	PostgreSQL (self-hosted)	애플리케이션 데이터 저장
Database	ORM	Drizzle ORM (우선) / Prisma (비교)	타입 안전 데이터베이스 쿼리
Database	Vector Store	pgvector(우선) → Qdrant/Milvus(실험)	벡터 임베딩 저장·검색
Database	Cache	Redis / Upstash Redis	세션 및 캐시
Storage	Object Storage	MinIO (S3 호환)	파일 및 이미지
Auth	Authentication	better-auth (우선) / Auth.js (대안)	인증 및 세션 관리
DevTools	Linter/Formatter	Biome (우선) / ESLint+Prettier (대안)	코드 품질 관리
DevTools	Package Manager	Bun (우선) / pnpm (대안)	의존성 관리
DevTools	AI Assistant	Cursor + GitHub Copilot	AI 기반 코드 작성 지원
Analytics	Web Analytics	Google Analytics 4 / Plausible (검토 중)	사용자 행동 분석
Support	Sponsorship	GitHub Sponsors	후원 시스템

기술 선택 여정과 고민 과정

프로젝트 철학 설정

핵심 동기: “최신 기술을 경험해보고 싶고, 세세하게 컨트롤할 수 있는 개발을 하고 싶다”

이 프로젝트는 단순한 기능 구현보다는 다양한 최신 기술을 깊이 있게 경험하는 학습 플랫폼이다. 따라서 기술 선택에서도 안정성보다는 학습 가치와 확장 가능성을 우선시했다.

Frontend Stack 선택 스토리

NextJS 15 + React 19 선택

React 19 & Next.js 15 정식 출시

React 19와 Next.js 15가 정식 릴리스되어 프로덕션 환경에서 안정적으로 사용 가능하다. 실험적 기능들이 검증된 프로덕션 레벨 기술로 성숙했다.

다양한 렌더링 방식 경험 계획:

• SSR (Server-Side Rendering): 사용자 대시보드, SEO가 중요한 페이지
• CSR (Client-Side Rendering): AI 채팅 인터페이스, 실시간 상호작용
• SSG (Static Site Generation): 문서, 랜딩 페이지
• ISR (Incremental Static Regeneration): 프로젝트 갤러리, 동적 콘텐츠
• Partial Prerendering (PPR): Next.js 15의 새로운 하이브리드 렌더링 방식

React 19 + NextJS 15 최신 기능 활용:

• React 19 정식 기능:
  • useOptimistic, useFormStatus, useActionState 훅
  • React Compiler (자동 메모이제이션)
  • Server Actions의 안정화
  • Improved Hydration 및 Suspense
• Next.js 15 정식 기능:
  • Turbopack 안정화 (개발 속도 5배 향상)
  • Partial Prerendering (PPR) 정식 지원
  • Enhanced Caching 전략
  • React 19 완전 통합

React 19를 선택한 이유

React 19의 최신 패턴들과 NextJS 15의 새로운 기능들을 실제 프로젝트에서 경험해보는 것이 목표다. 정식 릴리스로 인해 안정성이 보장되면서도 최신 기술 트렌드를 선경험하여 포트폴리오 차별화를 노릴 수 있다.

ShadCN + prompt-kit 조합

ShadCN - 기본 UI 컴포넌트

• 완전한 코드 소유권 (npm 패키지 아닌 코드 복사)
• 깔끔한 디자인, 자유로운 커스터마이징
• 방대한 커뮤니티 생태계

prompt-kit - AI 전용 컴포넌트

• AI 인터페이스에 특화된 고품질 컴포넌트
• OpenAI SDK, Vercel AI SDK와 통합
• ChatGPT 스타일의 검증된 UX 패턴

완벽한 조합

ShadCN으로 전체 앱 UI를 구축하고, prompt-kit으로 AI 챗봇 인터페이스만 특화 구현. 각자의 강점을 최대한 활용한다.

prompt-kit 주요 컴포넌트:

• PromptInput: 텍스트 입력 + 파일 업로드 + 액션 버튼
• Message: 사용자/AI 메시지 버블
• CodeBlock: 코드 하이라이팅 + 복사 버튼
• Markdown: AI 응답 마크다운 렌더링
• Source: RAG 소스 인용 표시
• Steps: 멀티 스텝 추론 시각화

AI Framework 선택의 고민

AI 프레임워크 선택

LangGraph와 AI SDK 모두 각자의 영역에서 강력한 도구다. LangGraph는 엔터프라이즈급 에이전트 시스템으로, AI SDK는 실시간 스트리밍에 최적화되었다.

LangGraph vs AI SDK 비교

항목	LangGraph (Python)	Vercel AI SDK (TypeScript)
세밀한 제어	⭐⭐⭐⭐⭐	⭐⭐⭐
React 통합	수동 (API 통신)	⭐⭐⭐⭐⭐ 네이티브
상태 관리	내장 체크포인트	클라이언트 상태
멀티 에이전트	⭐⭐⭐⭐⭐ 완벽 지원	⭐⭐ 제한적
스트리밍	SSE, WebSocket	⭐⭐⭐⭐⭐ 최적화
Tool Calling	완벽 지원	완벽 지원
학습 곡선	중~높음	낮음
생태계	LangChain 전체	Vercel 생태계
최신 모델	⭐⭐⭐⭐⭐ 즉시 지원	⭐⭐⭐⭐ 빠른 지원
타입 안전성	Python 타입 힌트	⭐⭐⭐⭐⭐ 완벽

LangGraph + LangChain 선택 이유 (재확인)

“langgraph가 더 세세하게 컨트롤이 가능해서” + “내가 해보고 싶은걸 다 해보는 이 프로젝트의 취지에 더 잘 맞아서”

LangChain v1 추가 도입 (2025년 10월)

LangChain이 정식 v1으로 출시되었다. 아직 완전히 안정화되지는 않았지만, 이 프로젝트의 “해보고 싶은 것을 다 해보기” 철학에 따라 적극 도입한다.

LangChain 도입 배경:

• 업계 표준: LLM 애플리케이션 개발의 사실상 표준 프레임워크
• LangGraph와의 시너지: LangGraph는 LangChain 생태계의 일부로 함께 사용 시 더 강력
• 풍부한 통합: 다양한 LLM, 벡터 DB, 도구들과의 즉시 연동
• 학습 가치: 실무에서 가장 많이 사용되는 AI 프레임워크 경험
• 실험 정신: stable 아니지만 최신 기술 빠르게 체험

참고 자료:

• LangChain Python Overview

LangGraph의 강점:

1. LangGraph Cloud/Server 정식 출시

   • 프로덕션 레벨 배포 솔루션
   • 내장 모니터링 및 로깅
   • 체크포인트 자동 관리

2. MCP (Model Context Protocol) 지원

   • Claude Desktop, Cursor와 직접 연동
   • 재사용 가능한 도구 생성
   • 표준화된 에이전트 인터페이스

3. 복잡한 워크플로우 구현

   • 조건부 라우팅
   • 루프 및 사이클
   • 병렬 실행
   • 에러 핸들링 및 재시도

4. 상태 영속성

   • PostgreSQL 기반 체크포인트
   • 세션 재개 가능
   • 히스토리 추적

구현 예시:

from langgraph.graph import StateGraph, END
from langgraph.checkpoint.postgres import PostgresSaver
 
# 복잡한 AI 워크플로우 정의
workflow = StateGraph(AgentState)
workflow.add_node("researcher", research_node)
workflow.add_node("writer", write_node)
workflow.add_node("reviewer", review_node)
 
# 조건부 라우팅
workflow.add_conditional_edges(
    "reviewer",
    should_continue,
    {
        "continue": "writer",
        "end": END
    }
)
 
# PostgreSQL 체크포인트
checkpointer = PostgresSaver.from_conn_string(DATABASE_URL)
app = workflow.compile(checkpointer=checkpointer)

최종 선택: LangGraph (확정)

“세세하게 컨트롤이 가능한” LangGraph가 “해보고 싶은걸 다 해보는 프로젝트 취지”와 완벽하게 일치했다. 2025년 업데이트로 프로덕션 레벨 도구로 성숙했으며, MCP 지원으로 확장성도 크게 향상되었다.

AI SDK와의 하이브리드 접근 (검토 중)

두 프레임워크의 장점 결합

LangGraph로 복잡한 AI 로직을 구현하고, AI SDK로 프론트엔드 스트리밍을 최적화하는 하이브리드 접근도 고려 중이다.

// Next.js API Route with AI SDK
import { streamText } from 'ai'
import { openai } from '@ai-sdk/openai'
 
export async function POST(req: Request) {
  const { messages } = await req.json()
  
  // LangGraph 백엔드 호출
  const langraphResponse = await fetch('http://langgraph-server/invoke', {
    method: 'POST',
    body: JSON.stringify({ messages })
  })
  
  // AI SDK로 스트리밍 최적화
  const result = await streamText({
    model: openai('gpt-4'),
    messages,
  })
  
  return result.toAIStreamResponse()
}

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)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

구체적 통합 방안(초기 설계):

1. LangConnect: 문서 관리 및 RAG 검색 담당

   • 프로젝트 문서 인덱싱
   • 사용자 질의에 대한 컨텍스트 검색
   • 벡터 임베딩 자동 관리

2. LangGraph: AI 에이전트 및 워크플로우 담당

   • 사용자 질의 분석 및 라우팅
   • 복잡한 AI 워크플로우 실행
   • 멀티 스텝 추론 및 의사결정

3. 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 생태계의 최신 기술 접근성과 협업 확장성을 우선시했다.

현대적 개발 도구 선택

ORM 선택: Drizzle vs Prisma

2025년 TypeScript ORM 트렌드

Drizzle ORM이 Prisma의 강력한 대안으로 부상하면서 TypeScript 생태계에 새로운 선택지를 제공하고 있다.

Drizzle ORM vs Prisma 비교표

항목	Drizzle ORM	Prisma
타입 안전성	완벽 (SQL-like, 추론 기반)	완벽 (스키마 생성 기반)
성능	매우 빠름 (직접 쿼리)	보통 (추가 레이어)
번들 사이즈	작음 (~15KB)	큼 (~100KB+)
학습 곡선	낮음 (SQL 유사)	중간 (새로운 문법)
마이그레이션	SQL 기반 (직접 제어)	자동 생성
Relations	명시적 정의	자동 추론
Edge Runtime	완벽 지원	제한적
개발자 경험	SQL에 익숙하면 우수	초보자 친화적
생태계	빠르게 성장 중	매우 성숙

최종 선택: Drizzle ORM (우선)

SQL에 가까운 문법으로 세밀한 제어가 가능하고, Edge Runtime 완벽 지원, 뛰어난 성능이 “세세한 컨트롤” 철학과 완벽히 일치한다.

Drizzle ORM 선택 이유:

1. SQL-like 문법: SQL 지식을 그대로 활용 가능
2. 제로 오버헤드: 런타임 성능 최적화
3. Edge-First: Cloudflare Workers, Vercel Edge에서 완벽 작동
4. TypeScript 우선: 완벽한 타입 추론
5. 작은 번들 사이즈: 프론트엔드 번들에 영향 최소화

// Drizzle ORM 사용 예시
import { drizzle } from 'drizzle-orm/postgres-js'
import { pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core'
 
export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  createdAt: timestamp('created_at').defaultNow(),
})
 
// 타입 안전한 쿼리
const allUsers = await db.select().from(users)
const user = await db.select().from(users).where(eq(users.email, 'test@example.com'))

Linter/Formatter: Biome vs ESLint+Prettier

2025년 코드 품질 도구 혁신

Biome이 ESLint와 Prettier를 하나로 통합하고 Rust 기반 성능으로 개발 경험을 크게 개선했다.

Biome vs ESLint+Prettier 비교표

항목	Biome	ESLint + Prettier
실행 속도	매우 빠름 (Rust)	느림 (Node.js)
설정 파일	1개 (biome.json)	2개 이상 (.eslintrc, .prettierrc)
기능 통합	Linting + Formatting	별도 도구
의존성 수	1개	10개 이상
IDE 통합	VS Code 공식 확장	여러 확장 필요
마이그레이션	자동 변환 도구 제공	-
규칙 수	200+ (증가 중)	300+ (매우 성숙)
생태계	빠르게 성장	매우 성숙
학습 곡선	낮음	중간

최종 선택: Biome (우선)

압도적인 성능, 단순한 설정, 통합된 경험이 개발 생산성을 크게 향상시킨다. ESLint+Prettier 조합 대비 설정 시간 90% 감소.

Biome 선택 이유:

1. 10-20배 빠른 성능: Rust 기반 엔진
2. Zero-Config: 즉시 사용 가능한 합리적 기본값
3. 올인원 솔루션: Linting과 Formatting 동시 처리
4. 작은 설치 크기: node_modules 크기 대폭 감소
5. 공식 VS Code 확장: 완벽한 IDE 통합

// biome.json - 간단한 설정
{
  "$schema": "https://biomejs.dev/schemas/1.5.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2
  }
}

Package Manager: Bun vs pnpm vs npm

2025년 패키지 매니저 경쟁 심화

Bun이 패키지 매니저를 넘어 올인원 JavaScript 런타임으로 진화하면서 개발 워크플로우 전체를 혁신하고 있다.

패키지 매니저 비교표

항목	Bun	pnpm	npm
설치 속도	매우 빠름 (네이티브)	빠름	보통
디스크 효율성	우수	매우 우수 (hard link)	낮음
런타임 포함	✅ JavaScript/TypeScript	❌	❌
번들러 포함	✅ 내장	❌	❌
테스트 러너	✅ 내장	❌	❌
호환성	높음 (npm 호환)	완벽	완벽
성숙도	빠르게 성장	성숙	매우 성숙
생태계	빠르게 확장	안정적	가장 넓음

최종 선택: Bun (우선), pnpm (대안)

Bun의 올인원 접근이 개발 도구 복잡도를 크게 줄이고, 최신 기술 경험이라는 프로젝트 목표와 완벽히 일치한다.

Bun 선택 이유:

1. 압도적 속도: npm 대비 10-20배 빠른 설치
2. 올인원 툴체인: 런타임 + 번들러 + 테스트 + 패키지 매니저
3. 네이티브 TypeScript: 트랜스파일 없이 직접 실행
4. 최신 기술: 최신 JavaScript/TypeScript 기능 즉시 지원
5. 개발 경험: 설정 파일 최소화, 즉시 시작

# Bun으로 프로젝트 시작
bun create next-app apphub
cd apphub
bun install        # 초고속 설치
bun dev           # Next.js 개발 서버
bun test          # 내장 테스트 러너
bun build         # 프로덕션 빌드

State Management: Zustand vs Jotai vs Valtio

2025년 상태 관리 트렌드

Redux의 시대가 저물고, 가벼운 상태 관리 라이브러리들이 주류가 되었다. Zustand, Jotai, Valtio가 각각의 철학으로 시장을 분할하고 있다.

상태 관리 라이브러리 비교표

항목	Zustand	Jotai	Valtio
번들 사이즈	작음 (~1KB)	매우 작음 (~0.8KB)	작음 (~1KB)
학습 곡선	낮음	중간 (Atomic)	낮음
API 스타일	Flux-like	Atomic	Proxy
DevTools	✅ Redux DevTools	✅ 자체 DevTools	✅ 제한적
TypeScript	완벽 지원	완벽 지원	완벽 지원
비동기 지원	수동	네이티브	수동
React 외 사용	가능	제한적	가능
선택적 렌더링	자동	자동	자동 (Proxy)

최종 선택: Zustand (우선), Jotai (검토)

Zustand의 단순함과 직관성이 빠른 개발에 유리하고, 필요시 Jotai의 Atomic 패턴으로 전환 가능성 열어둠.

Zustand 선택 이유:

1. 단순한 API: Redux 경험자에게 친숙
2. 보일러플레이트 최소: 코드량 대폭 감소
3. Redux DevTools: 익숙한 디버깅 도구
4. 점진적 채택: 프로젝트 일부에만 적용 가능
5. 프레임워크 무관: NextJS Server/Client 모두 사용

AI 개발 도구 (2025년 신규)

AI 기반 코딩의 새로운 시대

2025년 현재 AI 코딩 어시스턴트는 선택이 아닌 필수가 되었다. Cursor와 GitHub Copilot이 개발 생산성을 혁신하고 있다.

AI 코딩 어시스턴트 활용 계획

도구	용도	특징
Cursor	메인 IDE	컨텍스트 인식 코드 생성, 전체 파일 편집
GitHub Copilot	보조 도구	코드 자동완성, 주석→코드 변환
Claude (MCP)	아키텍처 논의	프로젝트 구조 설계, 기술 선택 자문

생산성 향상 기대치:

• 반복 코드 작성: 80% 시간 절감
• 보일러플레이트 생성: 90% 자동화
• 문서 작성: 70% 시간 절감
• 버그 수정: 40% 빠른 해결

Database 선택의 실용적 접근

PostgreSQL 18 도입 - 최신 성능 향상 경험

PostgreSQL 18 출시 (2025년 10월)

PostgreSQL 18이 최근 출시되었다. 비동기 I/O 지원을 비롯한 성능 개선이 매우 인상적이어서, 이 프로젝트의 “최신 기술 체험” 목표에 따라 즉시 도입한다.

PostgreSQL 18 주요 개선사항:

1. 비동기 I/O 혁신

   • 기존 동기식 디스크 읽기에서 진정한 비동기 I/O로 전환
   • 3가지 I/O 방식 선택 가능:
     • sync: 기존 동기 방식
     • worker: I/O 워커 프로세스 활용 (기본값)
     • io_uring: Linux 커널의 고성능 비동기 인터페이스

2. 성능 향상

   • 디스크 읽기 성능 최대 2.8배 향상
   • 클라우드 환경의 I/O 병목 현상 대폭 완화
   • effective_io_concurrency 기본값: 1 → 16으로 증가

3. 모니터링 개선

   • 새로운 pg_aios 뷰로 비동기 요청 상세 추적
   • 더 정확한 성능 분석 및 튜닝 가능

4. 설정 및 요구사항

   -- postgresql.conf
   io_method = 'io_uring'  -- 최고 성능 (Linux 5.1+ 필요)
   io_method = 'worker'    -- 기본값 (범용)

프로젝트 적용:

• Docker 이미지: pgvector/pgvector:pg18-bookworm 사용
• 벡터 검색 + RAG 워크로드에서 I/O 성능 향상 기대
• 클라우드 배포 시 비용 절감 효과 예상 (더 적은 리소스로 동일 성능)

참고 자료:

• PostgreSQL 18 비동기 I/O 분석 (한글)

Supabase의 결정적 장점(기록용)

과거 검토 기록

“Supabase는 귀찮은 작업들을 쉽고 빠르게 구현” → 초기에는 개발 속도를 위해 유력 후보였다.

장점 요약:

• PostgreSQL + pgvector + authentication를 한 번에 해결
• 복잡한 설정 작업들을 대폭 단순화
• 개발 속도 향상에 실질적 도움

최종 결정(갱신)

Supabase는 사용하지 않음. 메인 DB는 자체 운영 PostgreSQL 18, 벡터 스토어는 실험 목적에 따라 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 순차 실험(성능·확장성 비교)

배포 인프라 및 플랫폼 선택

2025년 배포 플랫폼 다양화

Vercel, Railway, Fly.io 등 개발자 친화적 플랫폼들이 크게 성장하면서 GCP/AWS 같은 전통적 클라우드의 대안으로 부상했다.

배포 플랫폼 비교표

항목	Vercel	Railway	Fly.io	GCP (Compute Engine)	홈서버
Next.js 최적화	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐
설정 복잡도	매우 낮음	낮음	중간	높음	매우 높음
무료 티어	관대함	관대함	$5 크레딧	$300 크레딧	초기 비용만
Edge Functions	✅ 네이티브	❌	✅ 제한적	❌	❌
Docker 지원	제한적	✅ 완벽	✅ 완벽	✅ 완벽	✅ 완벽
DB 호스팅	❌ (연동)	✅ 내장	❌ (연동)	✅ 별도 서비스	✅ 완전 제어
CI/CD	✅ 자동	✅ 자동	✅ 자동	수동 설정	수동 설정
비용 (월)	$0-20	$0-20	$5-30	$10-50	$25 (전기)
확장성	자동	자동	자동	수동	제한적
학습 가치	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐

단계별 배포 전략 재검토

Phase 1: 개발 & MVP (Vercel + Railway)

새로운 추천: Vercel + Railway 조합

Next.js 프론트엔드는 Vercel에, Python AI 서비스 + DB는 Railway에 배포하여 최고의 개발 경험과 빠른 MVP 검증을 달성한다.

컴포넌트	플랫폼	이유
Next.js Frontend	Vercel	Next.js 제작사, 제로 설정, Edge Functions
Python AI Service	Railway	Docker 완벽 지원, 자동 배포, DB 통합
PostgreSQL + pgvector	Railway	내장 PostgreSQL, 자동 백업
Redis	Railway	내장 Redis, 간편한 설정

장점:

• ✅ 제로 DevOps: 인프라 관리 불필요
• ✅ 자동 SSL/CDN: Vercel이 모두 처리
• ✅ Git 연동: Push만 하면 자동 배포
• ✅ 무료 시작: 양 플랫폼 모두 관대한 무료 티어
• ✅ 빠른 검증: MVP 구축 시간 70% 단축

Phase 2: 성장기 (GCP 또는 Fly.io)

• 시점: 월 방문자 10,000+ 또는 AI 요청 1,000+/일
• 목적: 비용 최적화 및 인프라 학습
• 플랫폼 선택:
  • Fly.io (추천): Docker 기반, 글로벌 엣지, 합리적 가격
  • GCP: 무료 크레딧 활용, 더 큰 학습 가치

Phase 3: 홈서버 마이그레이션

• 시점: 프로젝트 안정화 후 (6-12개월 후)
• 목적: 완전한 제어, 장기 비용 절감, 최대 학습 효과
• 준비사항:
  • 안정적인 인터넷 연결 (업로드 100Mbps+)
  • UPS (무정전 전원 공급 장치)
  • 백업 전략 수립

최종 추천 경로

[시작] Vercel + Railway
   ↓ (3-6개월, MVP 검증 완료)
[성장] Fly.io 또는 GCP 
   ↓ (6-12개월, 안정화)
[최종] 홈서버 (Mini PC + Docker)

2025년 업데이트: Railway가 게임 체인저

Railway의 등장으로 복잡한 GCP 설정 없이도 프로덕션급 인프라를 쉽게 구축할 수 있게 되었다. Vercel과 조합하면 최고의 DX(Developer Experience)를 제공한다.

도메인 전략

• 도메인: syshin0116.com (GoDaddy 구매 완료 또는 예정)
• DNS: Cloudflare (무료 CDN + DDoS 보호)
• 이메일: Cloudflare Email Routing (무료)

모니터링 & 분석

분석 도구 비교

도구	비용	모바일 앱	기능 범위	설정 복잡도	데이터 소유권	추천도
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 (무료, 개발자 친화적)

기술 스택 상세 비교

최종 선택된 기술 스택

검증된 최신 기술 스택

3개월간의 기술 발전과 안정화를 거쳐 프로덕션 레벨에서 자신있게 사용할 수 있는 스택으로 확정되었다.

레이어	컴포넌트	선택된 기술	버전	선택 이유
Frontend	웹 프레임워크	Next.js	15 (정식)	PPR, Turbopack, React 19 완전 통합
	UI 라이브러리	React	19 (정식)	React Compiler, 새로운 훅, Server Actions
	UI 컴포넌트	ShadCN/UI	Latest	코드 소유권, 완벽한 커스터마이징
	상태 관리	Zustand	Latest	단순함, DevTools, 점진적 채택
	서버 상태	TanStack Query	v5	최고의 데이터 페칭 솔루션
Backend	AI 프레임워크	LangGraph	Python Latest	세밀한 제어, MCP 지원, 엔터프라이즈급
	AI 생태계	LangChain	v1 (실험적)	LLM 애플리케이션 표준 프레임워크
	API 프레임워크	FastAPI	Latest	빠른 성능, 자동 문서화
	런타임	Python	3.11+	AI 생태계 최신 기술 즉시 지원
Database	메인 DB	PostgreSQL	18	비동기 I/O, 최대 2.8배 성능 향상
	ORM	Drizzle ORM	Latest	SQL-like, 타입 안전, Edge 지원
	Vector Store	pgvector	Latest (PG18)	단순성, SQL 통합 (→ Qdrant/Milvus 실험)
	Cache	Redis	7+	세션 관리, 고성능 캐싱
Auth	인증	better-auth	Latest	TypeScript 우선, 간편함, Drizzle 통합
DevTools	Package Manager	Bun	Latest	올인원 툴체인, 압도적 속도
	Linter/Formatter	Biome	Latest	Rust 기반, 통합 도구, 빠른 성능
	AI Assistant	Cursor + Copilot	Latest	AI 기반 코드 생성, 생산성 극대화
Deployment	Frontend	Vercel	-	Next.js 최적화, 자동 배포
	Backend + DB	Railway	-	Docker, 내장 DB, 자동 배포
	도메인/CDN	Cloudflare	-	DNS, CDN, DDoS 보호
Monitoring	분석	Google Analytics 4	-	무료, 강력한 기능
	후원	GitHub Sponsors	-	0% 수수료, 개발자 친화적

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 통합, 설정 간소화
예상 비용	$300무료크레딧\to 월$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 파일 그대로 이전	환경 차이 최소화
예상 비용	초기 $1,500+월전기료$25	장기적 비용 절약
학습 가치	풀스택 인프라 관리 경험	포트폴리오 차별화

도메인 및 SSL 전략

도메인 계획

syshin0116.com (GoDaddy 구매 예정) - 저렴한 가격과 개인 브랜딩을 동시에!

보안 및 인증

인증 솔루션 비교 및 선택

2025년 인증 솔루션 트렌드

NextAuth (Auth.js)의 복잡성과 설정 오버헤드로 인해 새로운 대안들이 부상하고 있다. better-auth, Clerk 등 개발자 경험을 개선한 솔루션들이 주목받고 있다.

인증 솔루션 비교표

항목	better-auth	Auth.js (NextAuth)	Clerk	Supabase Auth
타입 안전성	완벽한 TypeScript 지원	부분 지원	완벽 지원	좋음
설정 복잡도	낮음 (직관적)	높음 (복잡)	매우 낮음	낮음
코드 소유권	완전 소유	완전 소유	제한적 (SaaS)	제한적 (SaaS)
비용	무료 (오픈소스)	무료 (오픈소스)	유료 ($25/월~)	무료~유료
DB 통합	Drizzle/Prisma 네이티브	어댑터 필요	자체 관리	자체 관리
소셜 로그인	20+ 프로바이더	50+ 프로바이더	모든 주요 제공	주요 제공
고급 기능	2FA, Magic Link	기본 제공	모든 기능 포함	기본~고급
학습 곡선	낮음	중~높음	매우 낮음	낮음
세밀한 제어	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐	⭐⭐⭐

최종 선택: better-auth

“세세하게 컨트롤할 수 있는 개발” 철학에 가장 부합하는 솔루션이다. 완전한 타입 안전성, 낮은 설정 복잡도, Drizzle ORM과의 완벽한 통합이 결정적이었다.

better-auth 선택 이유:

1. TypeScript-First 설계: 완벽한 타입 추론과 자동완성
2. Drizzle ORM 네이티브 지원: 별도 어댑터 없이 즉시 통합
3. 직관적인 API: Auth.js 대비 설정 코드 70% 감소
4. 현대적 아키텍처: React 19 Server Actions와 완벽 호환
5. 완전한 코드 소유권: 모든 로직을 직접 제어 가능

구현 계획:

// better-auth 설정 예시
import { betterAuth } from "better-auth"
import { drizzleAdapter } from "better-auth/adapters/drizzle"
import { db } from "@/db"
 
export const auth = betterAuth({
  database: drizzleAdapter(db),
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    },
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
    },
  },
  emailAndPassword: {
    enabled: true,
  },
  session: {
    expiresIn: 60 * 60 * 24 * 7, // 7일
  },
})

보안 기능:

• 세션 관리: JWT 또는 Database Session 선택 가능
• 프로바이더: GitHub/Google OAuth + Email/Password
• 2FA 지원: TOTP 기반 2단계 인증
• Magic Link: 비밀번호 없는 로그인
• 라우팅 보호: NextJS Middleware 통합
• 서버-투-서버 보안: 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-10-06-AppHub-개인-프로젝트-플랫폼-기획 - 프로젝트 기획 및 비즈니스 로직
• 향후 추가 예정: 개발 환경 설정 가이드, 배포 매뉴얼

외부 참고 링크

• pgvector (PostgreSQL Extension)
• Qdrant Docs
• Milvus Docs
• LangGraph Cloud/Server Quickstart
• Auth.js (NextAuth) for Next.js
• Prisma Adapter (Auth.js)
• MinIO Documentation
• Traefik Documentation
• LangConnect (Evaluation Archive)