# PlanitAI KPI - 시스템 아키텍처 설계 **시리즈**: PlanitAI KPI 개발기 v3/16 **작성일**: 2025-12-07 **작성자**: GemEgg Dev Team --- ## 1. 아키텍처 원칙 ### 1.1 설계 원칙 ``` ┌─────────────────────────────────────────────────────┐ │ PlanitAI KPI 아키텍처 원칙 │ ├─────────────────────────────────────────────────────┤ │ │ │ 1. 단순함 우선 (Simplicity First) │ │ └── 복잡한 것보다 단순한 것을 선택 │ │ │ │ 2. 점진적 복잡도 (Progressive Complexity) │ │ └── MVP → Scale → Enterprise 단계별 확장 │ │ │ │ 3. 데이터 중심 (Data-Centric) │ │ └── 모든 것은 KPI 데이터를 중심으로 │ │ │ │ 4. AI 네이티브 (AI-Native) │ │ └── AI를 부가 기능이 아닌 핵심으로 │ │ │ │ 5. 확장 가능 (Extensible) │ │ └── 플러그인, API, 커스터마이징 │ │ │ └─────────────────────────────────────────────────────┘ ``` ### 1.2 아키텍처 진화 단계 | 단계 | 기간 | 아키텍처 | 특징 | |------|------|----------|------| | **Phase 1: MVP** | 0-3개월 | Monolith + Static | 단일 Python 앱, HTML 출력 | | **Phase 2: Growth** | 3-9개월 | Modular Monolith | 웹 앱, DB, API | | **Phase 3: Scale** | 9-18개월 | Microservices | 분산, 고가용성 | --- ## 2. 전체 시스템 구조 ### 2.1 Phase 1: MVP 아키텍처 ``` ┌─────────────────────────────────────────────────────────────┐ │ PlanitAI KPI MVP │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Google │ │ Python │ │ HTML │ │ │ │ Sheets │────▶│ App │────▶│ Report │ │ │ │ (데이터) │ │ (처리) │ │ (출력) │ │ │ └─────────────┘ └──────┬──────┘ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ Gemini AI │ │ │ │ (분석) │ │ │ └─────────────┘ │ │ │ │ 데이터 흐름: │ │ Sheets → Parser → KPI Engine → AI Analysis → HTML Gen │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 2.2 Phase 2: Growth 아키텍처 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ PlanitAI KPI Growth │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Frontend │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ │ │ Web │ │ Mobile │ │ API │ │ │ │ │ │ App │ │ PWA │ │ Clients │ │ │ │ │ │ (React) │ │ │ │ │ │ │ │ │ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │ │ │ └────────┼───────────────┼───────────────┼─────────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ API Gateway │ │ │ │ (FastAPI/Nginx) │ │ │ └──────────────────────────┬───────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────┼───────────────────────────────────┐ │ │ │ Backend Services │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ │ │ KPI │ │ AI │ │ Report │ │ │ │ │ │ Engine │ │ Service │ │ Service │ │ │ │ │ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │ │ │ └────────┼───────────────┼───────────────┼─────────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ Data Layer │ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ │ │ PostgreSQL │ │ Redis │ │ S3 │ │ │ │ │ │ (KPI) │ │ (Cache) │ │ (Files) │ │ │ │ │ └────────────┘ └────────────┘ └────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ External Integrations │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ │ │Google│ │freee │ │Slack │ │Gemini│ │ MF │ │ │ │ │ │Sheets│ │ │ │ │ │ AI │ │ │ │ │ │ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 2.3 Phase 3: Scale 아키텍처 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ PlanitAI KPI Scale │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ CDN (CloudFlare) │ │ │ └───────────────────────────┬───────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────┴───────────────────────────────┐ │ │ │ Load Balancer (ALB) │ │ │ └───────────────────────────┬───────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────┴───────────────────────────────┐ │ │ │ Kubernetes Cluster │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ API │ │ KPI │ │ AI │ │ Report │ │ │ │ │ │ Gateway │ │ Service │ │ Service │ │ Service │ │ │ │ │ │ (x3) │ │ (x3) │ │ (x2) │ │ (x2) │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Auth │ │ Notif │ │ Scheduler│ │ │ │ │ │ Service │ │ Service │ │ Service │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────┴───────────────────────────────┐ │ │ │ Data Layer │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │PostgreSQL│ │ Redis │ │ S3 │ │ Kafka │ │ │ │ │ │ (Aurora) │ │ Cluster │ │ │ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 3. 핵심 컴포넌트 설계 ### 3.1 KPI Engine (핵심) ``` ┌─────────────────────────────────────────────────────────────┐ │ KPI Engine │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ KPI Tree Manager │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Tree │ │ Node │ │Formula │ │Validator│ │ │ │ │ │ Builder │ │ Manager │ │ Engine │ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Calculation Engine │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Plan │ │ Actual │ │Forecast │ │Variance │ │ │ │ │ │ Calc │ │ Calc │ │ Calc │ │ Calc │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Analysis Engine │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │Bottleneck│ │ Trend │ │ Anomaly │ │Benchmark│ │ │ │ │ │ Detect │ │ Analyze │ │ Detect │ │ Compare │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 3.2 AI Service ``` ┌─────────────────────────────────────────────────────────────┐ │ AI Service │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Prompt Manager │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │ │ Templates │ Context Builder │ Optimizer │ │ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Analysis Types │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Summary │ │Bottleneck│ │Forecast │ │ Action │ │ │ │ │ │ Generate│ │ Analyze │ │ Generate│ │ Suggest │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Model Adapter │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Gemini │ │ GPT │ │ Claude │ │ │ │ │ │ Adapter │ │ Adapter │ │ Adapter │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 3.3 Data Integration Layer ``` ┌─────────────────────────────────────────────────────────────┐ │ Data Integration Layer │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Connectors │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Google │ │ freee │ │ Money │ │Salesforce│ │ │ │ │ │ Sheets │ │ │ │ Forward │ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Excel │ │ CSV │ │ API │ │ Webhook │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ ETL Pipeline │ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ │ │ Extract │─▶│Transform│─▶│Validate │─▶│ Load │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 4. 데이터 흐름 ### 4.1 KPI 데이터 파이프라인 ``` ┌─────────────────────────────────────────────────────────────┐ │ KPI Data Pipeline │ ├─────────────────────────────────────────────────────────────┤ │ │ │ External Sources Processing Storage │ │ ════════════════ ══════════ ═══════ │ │ │ │ ┌─────────────┐ │ │ │Google Sheets│──┐ │ │ └─────────────┘ │ ┌─────────────┐ ┌─────────────┐ │ │ ┌─────────────┐ │ │ │ │ │ │ │ │ freee │──┼────▶│ ETL Job │──▶│ PostgreSQL │ │ │ └─────────────┘ │ │ │ │ │ │ │ ┌─────────────┐ │ └──────┬──────┘ └──────┬──────┘ │ │ │ Salesforce │──┘ │ │ │ │ └─────────────┘ ▼ │ │ │ ┌─────────────┐ │ │ │ │ Validate │ │ │ │ │ & Enrich │ │ │ │ └──────┬──────┘ │ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ KPI Tree │──▶│ Cache │ │ │ │ Calculate │ │ (Redis) │ │ │ └──────┬──────┘ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ AI Analyze │ │ │ │ (Async) │ │ │ └─────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 4.2 실시간 분석 흐름 ``` User Request ──▶ API Gateway ──▶ Auth Check │ ▼ ┌─────────────┐ │ Cache Check │ └──────┬──────┘ │ ┌────────────────┼────────────────┐ │ Cache Hit │ Cache Miss │ ▼ ▼ │ Return Data ┌─────────────┐ │ │ KPI Engine │ │ └──────┬──────┘ │ │ │ ▼ │ ┌─────────────┐ │ │ AI Service │ │ │ (Optional) │ │ └──────┬──────┘ │ │ │ ▼ │ ┌─────────────┐ │ │ Update Cache│◀──────┘ └──────┬──────┘ │ ▼ Return Response ``` --- ## 5. 기술 결정 기록 (ADR) ### ADR-001: MVP는 정적 HTML 출력 **상황**: MVP에서 어떤 형태로 리포트를 제공할 것인가? **결정**: 정적 HTML 파일 생성 **이유**: - 서버 인프라 불필요 (비용 절감) - 브라우저에서 바로 열람 가능 - PDF 변환 용이 (인쇄) - 개발 속도 빠름 **결과**: 웹 서버 없이 리포트 배포 가능 --- ### ADR-002: Google Sheets를 1차 데이터 소스로 **상황**: 데이터를 어디서 가져올 것인가? **결정**: Google Sheets 우선 **이유**: - 사용자 친숙함 - 무료 - API 안정적 - 협업 기능 내장 - 나중에 DB 마이그레이션 가능 **트레이드오프**: - 대용량 데이터 한계 (10만 셀) - 오프라인 불가 --- ### ADR-003: Gemini AI 단일 모델로 시작 **상황**: 어떤 AI 모델을 사용할 것인가? **결정**: Gemini 2.0 Flash 단독 **이유**: - Google 에코시스템 통합 - 가격 대비 성능 우수 - Sheets API와 동일 인증 - 빠른 응답 시간 **나중에**: 멀티 모델 지원 (GPT, Claude) --- ## 6. 비기능 요구사항 ### 6.1 성능 목표 | 지표 | Phase 1 | Phase 2 | Phase 3 | |------|---------|---------|---------| | 리포트 생성 | < 30초 | < 10초 | < 5초 | | API 응답 | - | < 500ms | < 200ms | | AI 분석 | < 60초 | < 30초 | < 15초 | | 동시 사용자 | 1 | 100 | 10,000 | ### 6.2 확장성 목표 | 지표 | Phase 1 | Phase 2 | Phase 3 | |------|---------|---------|---------| | KPI 노드 | 100 | 1,000 | 10,000 | | 월별 데이터 | 12개월 | 60개월 | 120개월 | | 사업부 | 1 | 10 | 100 | | 사용자 | 1 | 50 | 1,000 | ### 6.3 가용성 목표 | Phase | SLA | RTO | RPO | |-------|-----|-----|-----| | Phase 1 | - | - | - | | Phase 2 | 99% | 4시간 | 24시간 | | Phase 3 | 99.9% | 1시간 | 1시간 | --- ## 7. 보안 아키텍처 개요 ``` ┌─────────────────────────────────────────────────────────────┐ │ Security Layers │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Layer 1: Network Security │ │ │ │ • HTTPS (TLS 1.3) │ │ │ │ • WAF (Web Application Firewall) │ │ │ │ • DDoS Protection │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Layer 2: Application Security │ │ │ │ • OAuth 2.0 / JWT │ │ │ │ • RBAC (Role-Based Access Control) │ │ │ │ • Input Validation │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Layer 3: Data Security │ │ │ │ • Encryption at Rest (AES-256) │ │ │ │ • Encryption in Transit (TLS) │ │ │ │ • Data Masking (PII) │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## 8. 결론 ### 아키텍처 요약 ``` ┌─────────────────────────────────────────────────────────────┐ │ │ │ Phase 1 (MVP): │ │ ├── Python CLI + Google Sheets + Gemini + HTML │ │ ├── 단일 사용자, 로컬 실행 │ │ └── 핵심 가치 검증 목적 │ │ │ │ Phase 2 (Growth): │ │ ├── FastAPI + React + PostgreSQL + Redis │ │ ├── 멀티 테넌트, 클라우드 배포 │ │ └── PMF 달성 목표 │ │ │ │ Phase 3 (Scale): │ │ ├── Kubernetes + Microservices + Kafka │ │ ├── 글로벌 서비스, 엔터프라이즈 │ │ └── 시장 확대 목표 │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### Next: 기술 스택 상세 선정 다음 편에서는 각 레이어별 구체적인 기술 선택과 그 이유를 상세히 다룹니다. --- **다음 편: [v4] 기술 스택 선정** *Python vs TypeScript, React vs Vue, PostgreSQL vs MongoDB 등 각 기술 선택의 근거와 트레이드오프를 분석합니다.*