# PlanitAI KPI - 기술 스택 선정
**시리즈**: PlanitAI KPI 개발기 v4/16
**작성일**: 2025-12-07
**작성자**: GemEgg Dev Team
---
## 1. 기술 선정 원칙
### 1.1 선정 기준
```
┌─────────────────────────────────────────────────────┐
│ 기술 스택 선정 기준 (우선순위 순) │
├─────────────────────────────────────────────────────┤
│ │
│ 1. 개발 속도 (Time to Market) │
│ └── MVP를 빠르게 검증할 수 있는가? │
│ │
│ 2. 팀 역량 (Team Expertise) │
│ └── 현재 팀이 잘 아는 기술인가? │
│ │
│ 3. 생태계 (Ecosystem) │
│ └── 라이브러리, 커뮤니티, 문서화가 풍부한가? │
│ │
│ 4. 확장성 (Scalability) │
│ └── 성장 시 대응 가능한가? │
│ │
│ 5. 비용 (Cost) │
│ └── 라이선스, 인프라, 인력 비용은? │
│ │
└─────────────────────────────────────────────────────┘
```
---
## 2. 언어 선정
### 2.1 백엔드 언어 비교
| 기준 | Python | TypeScript | Go | Java |
|------|:------:|:----------:|:--:|:----:|
| 개발 속도 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐ |
| AI/ML 생태계 | ⭐⭐⭐ | ⭐ | ⭐ | ⭐⭐ |
| 타입 안정성 | ⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| 성능 | ⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| 채용 용이성 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| **총점** | **14** | **12** | **11** | **12** |
### 2.2 결정: Python 3.11+
```python
# 선정 이유
"""
1. AI/ML 최고의 생태계
- google-generativeai (Gemini)
- pandas, numpy (데이터 처리)
- langchain (향후 확장)
2. 빠른 프로토타이핑
- 동적 타이핑 (MVP에 유리)
- 풍부한 라이브러리
3. Google API 공식 지원
- google-api-python-client
- 인증 처리 용이
4. 팀 역량
- 현재 팀 Python 숙련도 높음
- 채용 시장 풍부
"""
# Python 3.11+ 선택 이유
# - 성능 향상 (25%+)
# - 더 나은 에러 메시지
# - typing 개선
```
### 2.3 프론트엔드 언어: TypeScript
```typescript
// Phase 2 웹앱 개발 시
// TypeScript + React 선택 이유
/*
1. 타입 안정성
- 런타임 에러 감소
- IDE 지원 우수
2. React 생태계
- 풍부한 UI 컴포넌트
- 차트 라이브러리 풍부
3. 팀 역량
- 프론트엔드 TypeScript 표준
4. SSR/SSG 지원
- Next.js로 SEO 대응
*/
```
---
## 3. 프레임워크 선정
### 3.1 백엔드 프레임워크 (Phase 2)
| 기준 | FastAPI | Django | Flask | Express |
|------|:-------:|:------:|:-----:|:-------:|
| 성능 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| API 문서화 | ⭐⭐⭐ | ⭐⭐ | ⭐ | ⭐ |
| 비동기 | ⭐⭐⭐ | ⭐⭐ | ⭐ | ⭐⭐⭐ |
| 학습 곡선 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| 타입 힌트 | ⭐⭐⭐ | ⭐⭐ | ⭐ | N/A |
| **총점** | **15** | **10** | **8** | **10** |
### 3.2 결정: FastAPI
```python
# FastAPI 선택 이유
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI(
title="PlanitAI KPI API",
description="AI-powered KPI Management Platform",
version="1.0.0"
)
class KPICreate(BaseModel):
name: str
category: str
unit: str
formula: str | None = None
@app.post("/api/kpis")
async def create_kpi(kpi: KPICreate):
"""
FastAPI 장점:
1. 자동 OpenAPI 문서 생성
2. Pydantic으로 타입 검증
3. async/await 네이티브 지원
4. 높은 성능 (Starlette 기반)
"""
return {"id": "kpi_001", **kpi.dict()}
```
### 3.3 프론트엔드 프레임워크 (Phase 2)
| 기준 | Next.js | React SPA | Vue | Svelte |
|------|:-------:|:---------:|:---:|:------:|
| SSR/SSG | ⭐⭐⭐ | ⭐ | ⭐⭐⭐ | ⭐⭐ |
| 생태계 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐ |
| 성능 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| 채용 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐ |
| **총점** | **12** | **9** | **9** | **7** |
### 3.4 결정: Next.js 14+
```typescript
// Next.js 14 App Router 사용
// app/dashboard/page.tsx
export default async function DashboardPage() {
// Server Component - 서버에서 데이터 fetch
const kpis = await fetchKPIs();
return (
KPI Dashboard
);
}
/*
Next.js 14 선택 이유:
1. App Router - 더 나은 레이아웃 시스템
2. Server Components - 빠른 초기 로딩
3. API Routes - 백엔드 프록시 가능
4. Vercel 배포 - 간편한 CI/CD
*/
```
---
## 4. 데이터베이스 선정
### 4.1 RDBMS 비교
| 기준 | PostgreSQL | MySQL | SQLite |
|------|:----------:|:-----:|:------:|
| JSON 지원 | ⭐⭐⭐ | ⭐⭐ | ⭐ |
| 확장성 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ |
| 복잡 쿼리 | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
| 클라우드 지원 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ |
| **총점** | **12** | **10** | **5** |
### 4.2 결정: PostgreSQL + SQLite
```sql
-- Phase 1 (MVP): SQLite
-- 단일 파일, 설치 불필요, 로컬 개발에 적합
-- Phase 2+: PostgreSQL
-- KPI 트리 데이터를 JSONB로 저장
CREATE TABLE kpi_trees (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
organization_id UUID NOT NULL,
name VARCHAR(255) NOT NULL,
tree_structure JSONB NOT NULL, -- KPI 트리 구조
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- JSONB 인덱스로 빠른 조회
CREATE INDEX idx_kpi_tree_structure
ON kpi_trees USING GIN (tree_structure);
-- 예시 tree_structure
/*
{
"root": "kgi_sales",
"nodes": {
"kgi_sales": {
"name": "売上高",
"formula": "contract_count * contract_price",
"children": ["kpi_contract_count", "kpi_contract_price"]
},
"kpi_contract_count": {
"name": "契約数",
"formula": "close_rate * meetings",
"children": ["kpi_close_rate", "kpi_meetings"]
}
}
}
*/
```
### 4.3 캐시: Redis
```python
# Redis 사용 케이스
import redis
import json
r = redis.Redis(host='localhost', port=6379, db=0)
# 1. KPI 계산 결과 캐싱
def get_kpi_summary(org_id: str, month: str):
cache_key = f"kpi:summary:{org_id}:{month}"
# 캐시 확인
cached = r.get(cache_key)
if cached:
return json.loads(cached)
# 계산 후 캐시 저장 (TTL: 1시간)
result = calculate_kpi_summary(org_id, month)
r.setex(cache_key, 3600, json.dumps(result))
return result
# 2. AI 분석 결과 캐싱 (비용 절감)
def get_ai_analysis(kpi_data_hash: str):
cache_key = f"ai:analysis:{kpi_data_hash}"
cached = r.get(cache_key)
if cached:
return json.loads(cached)
# Gemini API 호출 후 캐시 (TTL: 24시간)
result = generate_ai_analysis(kpi_data_hash)
r.setex(cache_key, 86400, json.dumps(result))
return result
```
---
## 5. AI/ML 스택
### 5.1 LLM 선택
| 기준 | Gemini | GPT-4 | Claude | Llama |
|------|:------:|:-----:|:------:|:-----:|
| 가격 | ⭐⭐⭐ | ⭐ | ⭐⭐ | ⭐⭐⭐ |
| 성능 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ |
| API 안정성 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐ |
| Google 연동 | ⭐⭐⭐ | ⭐ | ⭐ | ⭐ |
| **총점** | **12** | **8** | **8** | **7** |
### 5.2 결정: Gemini 2.0 Flash (Primary)
```python
# AI 스택 구성
import google.generativeai as genai
# Primary: Gemini 2.0 Flash
# - 가격: $0.075/1M input, $0.30/1M output
# - 속도: 빠름 (< 5초)
# - 용도: 일반 분석, 요약
# Secondary: Gemini 1.5 Pro (필요 시)
# - 가격: $1.25/1M input
# - 용도: 복잡한 분석, 긴 컨텍스트
class AIModelSelector:
def __init__(self):
genai.configure(api_key=os.getenv("GOOGLE_API_KEY"))
def select_model(self, task_type: str) -> str:
"""태스크에 따른 모델 선택"""
if task_type in ["summary", "simple_analysis"]:
return "gemini-2.0-flash"
elif task_type in ["complex_analysis", "long_context"]:
return "gemini-1.5-pro"
else:
return "gemini-2.0-flash" # 기본값
```
### 5.3 향후 확장: Multi-Model
```python
# Phase 2: Multi-Model Architecture
from abc import ABC, abstractmethod
class LLMAdapter(ABC):
@abstractmethod
async def generate(self, prompt: str) -> str:
pass
class GeminiAdapter(LLMAdapter):
async def generate(self, prompt: str) -> str:
# Gemini API 호출
pass
class OpenAIAdapter(LLMAdapter):
async def generate(self, prompt: str) -> str:
# OpenAI API 호출
pass
class ClaudeAdapter(LLMAdapter):
async def generate(self, prompt: str) -> str:
# Anthropic API 호출
pass
# 팩토리 패턴으로 모델 선택
def get_llm_adapter(model: str) -> LLMAdapter:
adapters = {
"gemini": GeminiAdapter(),
"gpt-4": OpenAIAdapter(),
"claude": ClaudeAdapter(),
}
return adapters.get(model, GeminiAdapter())
```
---
## 6. 인프라 스택
### 6.1 Phase별 인프라
```
┌─────────────────────────────────────────────────────────────┐
│ Infrastructure Stack │
├─────────────────────────────────────────────────────────────┤
│ │
│ Phase 1 (MVP): Local/Simple │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ • Python Script (로컬 실행) │ │
│ │ • Google Sheets (데이터) │ │
│ │ • HTML Files (출력) │ │
│ │ • 비용: $0/월 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Phase 2 (Growth): Cloud Simple │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ • Vercel (Frontend - Next.js) │ │
│ │ • Railway/Render (Backend - FastAPI) │ │
│ │ • Supabase (PostgreSQL + Auth) │ │
│ │ • Upstash (Redis) │ │
│ │ • 비용: ~$50-100/월 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Phase 3 (Scale): Cloud Enterprise │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ • AWS/GCP (Full Stack) │ │
│ │ • EKS/GKE (Kubernetes) │ │
│ │ • Aurora/Cloud SQL (Managed DB) │ │
│ │ • ElastiCache/Memorystore (Redis) │ │
│ │ • 비용: ~$500-2000/월 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 6.2 Phase 2 추천 스택
```yaml
# 비용 효율적인 Phase 2 스택
Frontend:
platform: Vercel
framework: Next.js 14
pricing: Free tier (충분)
Backend:
platform: Railway
framework: FastAPI
pricing: $5/월 (Hobby) → $20/월 (Pro)
Database:
platform: Supabase
engine: PostgreSQL
pricing: Free tier → $25/월 (Pro)
Cache:
platform: Upstash
engine: Redis
pricing: Free tier (10K commands/day)
Auth:
platform: Supabase Auth
pricing: Included
File Storage:
platform: Supabase Storage
pricing: Included
Total: $30-50/월 (초기)
```
---
## 7. 차트/시각화 라이브러리
### 7.1 비교
| 기준 | Chart.js | D3.js | Recharts | ECharts |
|------|:--------:|:-----:|:--------:|:-------:|
| 학습 곡선 | ⭐⭐⭐ | ⭐ | ⭐⭐⭐ | ⭐⭐ |
| 커스터마이징 | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐ |
| 번들 크기 | ⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐ |
| React 통합 | ⭐⭐ | ⭐ | ⭐⭐⭐ | ⭐⭐ |
| 트리 시각화 | ⭐ | ⭐⭐⭐ | ⭐ | ⭐⭐⭐ |
| **총점** | **10** | **11** | **11** | **11** |
### 7.2 결정: 복합 사용
```typescript
// Phase 1: Chart.js (HTML 리포트)
// - 간단한 바, 라인, 레이더 차트
// - 번들 불필요 (CDN)
// Phase 2: Recharts + D3.js
// 일반 차트: Recharts (React 친화적)
import { BarChart, Bar, XAxis, YAxis } from 'recharts';
function KPIBarChart({ data }) {
return (
);
}
// KPI 트리: D3.js (복잡한 트리 구조)
import * as d3 from 'd3';
function KPITree({ treeData }) {
// D3 tree layout으로 복잡한 KPI 트리 렌더링
const treeLayout = d3.tree().size([width, height]);
// ...
}
```
---
## 8. 개발 도구
### 8.1 개발 환경
```yaml
# 개발 도구 스택
IDE:
- VS Code (Primary)
- Extensions:
- Python
- Pylance
- ESLint
- Prettier
- GitHub Copilot
Version Control:
- Git
- GitHub (Repository)
- Conventional Commits
Package Manager:
- Python: uv (빠른 속도)
- Node.js: pnpm (디스크 효율)
Linting/Formatting:
- Python: ruff (빠른 속도)
- TypeScript: ESLint + Prettier
- Pre-commit hooks
Testing:
- Python: pytest
- TypeScript: Vitest
- E2E: Playwright
```
### 8.2 CI/CD
```yaml
# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
test-python:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: astral-sh/setup-uv@v4
- run: uv sync
- run: uv run pytest --cov
test-frontend:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v2
- run: pnpm install
- run: pnpm test
- run: pnpm build
```
---
## 9. 기술 스택 요약
### 9.1 최종 스택
```
┌─────────────────────────────────────────────────────────────┐
│ PlanitAI KPI Technology Stack │
├─────────────────────────────────────────────────────────────┤
│ │
│ Backend: │
│ ├── Language: Python 3.11+ │
│ ├── Framework: FastAPI (Phase 2+) │
│ ├── ORM: SQLAlchemy 2.0 │
│ └── Task Queue: Celery + Redis (Phase 2+) │
│ │
│ Frontend: │
│ ├── Language: TypeScript │
│ ├── Framework: Next.js 14 (App Router) │
│ ├── UI: Tailwind CSS + shadcn/ui │
│ └── Charts: Recharts + D3.js │
│ │
│ Database: │
│ ├── Primary: PostgreSQL (Supabase) │
│ ├── Cache: Redis (Upstash) │
│ └── MVP: SQLite │
│ │
│ AI/ML: │
│ ├── Primary: Gemini 2.0 Flash │
│ ├── Secondary: Gemini 1.5 Pro │
│ └── Future: GPT-4, Claude (Adapter Pattern) │
│ │
│ Infrastructure: │
│ ├── Frontend: Vercel │
│ ├── Backend: Railway │
│ ├── Database: Supabase │
│ └── Future: AWS/GCP (Kubernetes) │
│ │
│ DevOps: │
│ ├── VCS: GitHub │
│ ├── CI/CD: GitHub Actions │
│ ├── Monitoring: Sentry + Vercel Analytics │
│ └── IaC: Terraform (Phase 3) │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 9.2 비용 추정
| Phase | 월 비용 | 포함 내용 |
|-------|---------|-----------|
| Phase 1 | $0-10 | Gemini API만 |
| Phase 2 | $50-100 | Vercel + Railway + Supabase |
| Phase 3 | $500-2000 | AWS/GCP Full Stack |
---
**다음 편: [v5] 데이터 모델 설계**
*KPI 트리, 사용자, 조직 등 핵심 엔티티의
데이터 모델과 스키마 설계를 다룹니다.*