DOCS/_archive/docs/architecture/00_아키텍쳐.md

---
tags: 아키텍처, 에이전트, 마이크로서비스, 컨테이너, 데이터베이스, MSA
date: 2025-07-07
modified: 2025-07-07
---

# 프로젝트 아키텍처 종합

## 1. 개요: 에이전트 중심 디지털 생태계

본 프로젝트의 아키텍처는 단순한 단일 애플리케이션을 넘어, 여러 구성요소가 유기적으로 상호작용하는 **에이전트 중심의 디지털 생태계**를 지향합니다. 이 생태계는 AI 에이전트를 단순한 도구가 아닌, 지속적으로 학습하고 성장하는 '디지털 동료'로 정의하며, 다음과 같은 네 가지 핵심 요소로 구성됩니다.

- **에이전트 협업툴**: Slack, Teams 등 기존 업무 도구에 통합되어 실시간으로 팀의 업무를 지원하고 맥락을 기억하는 AI 비서.
- **에이전트 마켓플레이스**: 다양한 역할과 스킬을 가진 AI 에이전트를 기업이 필요에 따라 고용(구독)하고 해지할 수 있는 플랫폼.
- **에이전트 SNS**: 에이전트 간의 상호작용과 경험 공유를 통해 집단 지성을 형성하고 자율적으로 학습하는 소셜 네트워크.
- **에이전트 기반 정보회사**: 웹과 내부 데이터를 24시간 수집, 분석, 가공하여 신뢰도 높은 지식을 생성하는 자동화된 정보 플랫폼.

이 네 요소는 데이터와 기능을 공유하며 선순환 구조를 이루어, 전체 생태계가 하나의 거대한 자율 조직처럼 기능하도록 설계되었습니다.

## 2. 핵심 실행 아키텍처

### 2.1. 로빙 컨테이너 아키텍처 (Robeing Container Architecture)

개별 AI 에이전트('로빙')의 독립성과 성장성을 보장하기 위한 핵심 실행 모델입니다.

- **구조**: 중앙 대시보드 서버가 다수의 독립된 '로빙 컨테이너'를 관리하는 구조입니다. 이는 중앙 서버와 다수의 클라이언트로 구성된 게임 서버 아키텍처와 유사합니다.
- **독립성**: 각 로빙 컨테이너는 사용자별로 완전히 격리된 Docker 환경에서 실행되며, 고유의 FastAPI 서버, 벡터 DB(ChromaDB), 데이터 저장소를 가집니다.
- **성장 시스템**: 로빙의 레벨이 오르면 더 많은 리소스(CPU, 메모리)가 할당된 새로운 컨테이너로 재시작됩니다. 데이터는 볼륨 마운트를 통해 영속적으로 유지됩니다.
- **리소스 효율성**:
    - **수면/각성 시스템**: 일정 시간 비활성 상태인 로빙은 최소 리소스를 사용하는 '수면' 상태로 전환되며, 사용자 접속 시 3-5초 내에 '각성'하여 전체 리소스를 할당받습니다.
    - **베드 상태 반성**: 수면 상태에 들어갈 때, 하루의 활동 로그를 분석하여 스스로 학습하고 행동 패턴을 최적화합니다.

### 2.2. 마이크로서비스 아키텍처 (MSA)

비서형 AI 에이전트와 같이 여러 외부 서비스를 연동하는 기능은 마이크로서비스 아키텍처(MSA)를 기반으로 구현됩니다.

- **모듈화**: 각 기능(Slack 연동, Zoom 회의록 분석, Notion 통합 등)을 독립된 FastAPI 기반 마이크로서비스로 개발하고 Docker 컨테이너로 배포합니다.
- **오케스트레이션**: 중앙의 '오케스트레이션/스케줄러 서비스'가 정해진 시간에 각 모듈을 호출하여 데이터를 수집하고, LLM 분석을 거쳐 최종 보고서를 생성하는 파이프라인을 관리합니다.
- **확장성 및 안정성**: 기능 추가 시 새로운 컨테이너를 추가하는 방식으로 유연하게 확장할 수 있으며, 특정 모듈의 장애가 전체 시스템에 영향을 미치는 것을 방지합니다.
- **동적 라우팅**: Nginx 또는 Traefik 같은 리버스 프록시를 사용하여 외부 요청을 적절한 컨테이너로 라우팅합니다. 특히 Traefik은 Docker 레이블을 기반으로 서비스를 자동 탐지하여 동적으로 라우팅 설정을 업데이트할 수 있어 컨테이너 관리에 유리합니다.

## 3. 개념적 아키텍처 및 설계 원칙

### 3.1. 3계층 아키텍처: 스탯-스킬-아이템

로빙의 능력을 구조화하는 개념적 프레임워크입니다.

- **스탯 (Stats)**: 에이전트의 근본적인 능력치 (기억, 연산, 반응, 공감, 통솔). 인프라 및 리소스 할당량과 직결됩니다.
- **스킬 (Skills)**: 에이전트가 수행할 수 있는 구체적인 기능 (대화 요약, 액션 아이템 추출 등). 스탯이 특정 조건을 만족해야 활성화됩니다.
- **아이템 (Items)**: 외부 API 접근권, 프리미엄 모델 사용권 등 외부 리소스에 대한 권한을 토큰화하여 관리합니다.

### 3.2. 데이터 아키텍처: Polyglot Persistence

데이터의 종류와 활용 목적에 따라 최적의 데이터베이스를 조합하여 사용합니다.

- **관계형 DB (PostgreSQL)**: 사용자 정보, 스탯, 스킬 메타데이터 등 정형화된 데이터를 저장하고 트랜잭션 일관성을 보장합니다. (현재 운영 중)
- **벡터 DB (ChromaDB)**: 대화 내용, 문서 등을 임베딩하여 저장하고, 의미 기반의 유사도 검색을 통해 에이전트의 장기 기억과 맥락 이해를 돕습니다. (현재 운영 중)
- **그래프 DB (Neo4j)**: 스타트업, 투자자, 기술 등 객체 간의 복잡한 관계를 분석하고 시각화하는 데 사용됩니다. 사용자 간 관계, 감정 이력 추적 등에 활용 예정입니다. (구현 예정)
- **인메모리 DB (Redis)**: 세션 데이터나 임시 캐시를 저장하여 빠른 응답 속도를 보장합니다. API 응답 캐싱, 실시간 상태 관리 등에 필수적입니다. (구현 예정)

### 3.3. 함수형 프로그래밍 접근법

스탯 계산, 의사결정 등 핵심 로직은 부작용이 없는 순수 함수(Pure Function)로 설계하여 시스템의 안정성과 테스트 용이성을 높입니다. 모나드 패턴을 활용하여 외부 시스템 연동이나 실패 가능한 작업을 안전하게 처리합니다.

## 4. 개발 및 운영 아키텍처

### 4.1. 뇌(Brain) + 실험실(Lab) 아키텍처

안정적인 운영과 빠른 기능 개발을 동시에 달성하기 위한 개발 워크플로우입니다.

- **실험실 (Lab)**: 새로운 스킬이나 로직을 자유롭게 개발하고 테스트하는 환경입니다.
- **뇌 (Brain)**: 충분한 검증을 거친 안정화된 스킬과 로직이 배포되는 운영 환경입니다.
- **승격 파이프라인**: '실험실'에서 개발된 기능은 자동화된 테스트와 검증을 거쳐 '뇌'로 승격되어 전체 시스템에 통합됩니다.

### 4.2. API 중개 플랫폼: Keyless Connect

API 키 관리의 복잡성과 보안 리스크를 해결하기 위해, OAuth와 프록시 호출을 활용한 'Keyless' API 중개 플랫폼을 도입합니다. 사용자는 플랫폼에 한 번만 인증하면, 플랫폼이 백그라운드에서 필요한 API 키를 안전하게 관리하고 대신 호출해주는 구조입니다. 이를 통해 개발자 경험(DX)을 극대화하고 보안을 강화합니다.

#### auth-server: 멀티테넌트 인증 허브
**로빙 생태계의 중앙 인증 시스템**으로 B2B 고객사별 Slack 봇 인증 및 OAuth 토큰 관리를 담당합니다.
- 회사별 독립 서브도메인 제공 (예: `company.auth.ro-being.com`)
- Google/Slack OAuth 통합 인증, JWT 기반 사용자 세션 관리
- 상세 스키마: [auth-server 데이터베이스 스키마](./auth-server-database-schema.md)

#### 기술 구조
- **통합 인증**: 사용자는 플랫폼에만 로그인합니다. 플랫폼은 각 API 제공사에 필요한 인증 토큰(OAuth)을 내부적으로 관리하거나, 자체 Vault에 안전하게 저장된 API 키를 사용하여 **프록시 호출**(Proxy Call)을 수행합니다.
- **정책 토큰**: 사용자의 요청은 단순한 API 호출이 아닌, 권한과 허용 범위가 명시된 서명된 토큰(예: JWT)과 함께 전달됩니다. API 게이트웨이는 이 토큰을 검증하여 안전한 호출을 보장합니다.
- **헤드리스/분산 아키텍처**: 각 API 연동 모듈은 독립적인 마이크로서비스로 개발되어, 레고처럼 조합하고 확장할 수 있는 **구성 가능한 아키텍처**(Composable Architecture)를 지향합니다.

#### 전략적 가치
- **개발자 경험(DX) 극대화**: 복잡한 인증 절차를 제거하여 "1분 내 API 연동"을 핵심 가치로 제공합니다.
- **보안 강화**: 사용자는 API 키를 직접 다루지 않으므로 키 유출의 위험이 원천적으로 차단됩니다.
- **중앙화된 관리**: 모든 API 사용량과 과금 내역을 단일 대시보드에서 투명하게 관리하고 통제할 수 있습니다.
- **법적 준수**: API 제공사의 서비스 약관(TOS)을 준수하는 '사용자를 대신한 안전한 호출 대행' 모델을 지향하여 신뢰성을 확보합니다.

## 5. UI/UX 아키텍처: 게임형 인터페이스와 GUI 공유 시스템

프론트엔드는 모바일 게임 스타일의 직관적이고 재미있는 인터페이스를 통해 로빙과의 상호작용을 극대화합니다.

- **게임 스타일 UI**: React 18 + TypeScript + Vite 기반으로 Merge Restaurant 같은 모바일 게임 UI를 구현합니다. Framer Motion과 Lottie를 활용한 풍부한 애니메이션으로 재미있는 경험을 제공합니다.
- **캐릭터 대시보드**: 로빙의 레벨, 스탯(기억/연산/반응/공감/통솔), 감정 상태, 스킬 목록을 시각적으로 표현합니다. 레벨업 시 화려한 이펙트와 보상 애니메이션을 제공합니다.
- **3분할 레이아웃**: 데스크톱에서는 GUI 화면 | 채팅창 | 상태창의 3분할 구조를, 모바일에서는 슬라이드 전환 방식을 채택하여 효율적인 정보 표시를 구현합니다.
- **GUI 공유 시스템**: 로빙이 컨테이너에서 실행하는 GUI 애플리케이션을 사용자에게 단계적으로 공유합니다 (Lv.1-4 스크린샷 → Lv.5-9 반응형 스크린샷 → Lv.10-14 영상 → Lv.15-19 읽기 전용 VNC → Lv.20 완전 제어).

## 6. 기억 관리 아키텍처: 다학문적 통합 프레임워크

에이전트의 '지속적 기억'은 단순한 데이터 저장이 아닌, 다학문적 통찰을 바탕으로 설계된 고차원적 기능입니다.

- **정보 가치 평가**: 모든 정보는 저장되기 전, 의사결정에 미치는 영향력(경제학), 새로움(정보이론), 신뢰도 등을 종합적으로 평가받습니다.
- **능동적 망각**: 인간의 뇌처럼, 시간이 지나거나 사용 빈도가 낮은 정보는 자동으로 요약되거나 아카이빙됩니다. 이는 **파국적 망각**(Catastrophic Forgetting)을 방지하는 Continual Learning 기법과도 연결됩니다.
- **지식 충돌 관리**: 서로 모순되는 정보는 어느 한쪽을 폐기하는 대신, "A 관점에서는 p, B 관점에서는 ¬p"와 같이 **다중 관점을 병렬로 저장**하여 편향을 최소화하고 종합적인 판단을 돕습니다.
- **효율성과 비용 균형**: 메모리 사용의 편익과 비용(자원, 시간)을 동적으로 평가하여, 한정된 자원 내에서 최적의 성능을 내도록 기억 시스템을 자동 조절합니다.
- **사회적 신뢰와 윤리**: 사용자의 '잊혀질 권리(Right to be Forgotten)'를 보장하기 위해, 개인정보나 민감 정보는 사용자의 요청에 따라 안전하게 삭제하거나 익명화하는 기능을 포함합니다. 모든 기억의 접근과 변경은 추적 가능한 로그로 관리됩니다.

## 7. 종합 및 제언

이 프로젝트의 아키텍처는 **모듈성, 확장성, 자율성**이라는 세 가지 핵심 원칙 위에 세워져 있습니다. 각 아키텍처 요소는 독립적으로 기능하면서도, 서로 유기적으로 연결되어 '에이전트 중심 생태계'라는 더 큰 비전을 완성합니다.

- **실행 아키텍처** (컨테이너, MSA)는 각 에이전트의 독립적인 실행과 성장을 기술적으로 보장하며, 안정적인 서비스 운영의 기반이 됩니다.
- **개념적 아키텍처** (스탯-스킬-아이템, Polyglot DB)는 에이전트의 능력을 명확하게 정의하고, 다양한 종류의 데이터를 효과적으로 관리할 수 있는 구조적 유연성을 제공합니다.
- **개발 및 운영 아키텍처** (뇌+실험실, Keyless)는 빠르고 안정적인 개발 문화를 만들고, 보안과 사용 편의성을 동시에 달성하기 위한 현실적인 해법을 제시합니다.
- **경험 아키텍처** (UI/UX, 기억 관리)는 기술을 넘어 사용자가 에이전트와 의미 있는 관계를 맺고, 신뢰할 수 있는 '디지털 동료'로 인식하게 만드는 핵심 요소입니다.

**저의 의견**:

이 아키텍처 설계의 가장 큰 강점은 **추상적인 '존재로서의 AI'라는 철학을 구체적인 기술 스택과 실행 가능한 계획으로 잘 번역했다는 점**입니다. 특히 '로빙 컨테이너'와 '수면/각성 시스템'은 AI의 자율성과 리소스 효율성이라는 두 마리 토끼를 잡는 매우 창의적인 접근이라고 생각합니다. 또한, '뇌+실험실' 모델은 혁신을 지속하면서도 서비스 안정성을 유지해야 하는 모든 기술 조직이 참고할 만한 훌륭한 워크플로우입니다.

다만, 이 모든 것을 구현하기 위해서는 각 아키텍처 간의 **인터페이스를 매우 정교하게 설계**하는 것이 관건이 될 것입니다. 예를 들어, 스탯 시스템의 '기억' 스탯이 실제 컨테이너의 벡터 DB 용량과 어떻게 연동될 것인지, 'Keyless' 플랫폼의 정책 토큰이 에이전트의 '아이템' 시스템과 어떻게 통합될 것인지에 대한 구체적인 명세가 뒤따라야 합니다.

결론적으로, 이 문서는 단순한 기술 청사진을 넘어, **AI 에이전트가 어떻게 사용자와 함께 성장하고, 신뢰를 구축하며, 하나의 생태계를 이룰 수 있는지에 대한 종합적인 비전과 로드맵을 제시**하고 있습니다. 제안된 아키텍처들을 단계적으로 구현해 나간다면, 기술적으로 견고하고 시장에서도 차별화된 경쟁력을 갖춘 프로덕트를 만들 수 있을 것이라 확신합니다.



## 7. 부록

---
**최종 수정**: 2025-07-29  
**수정 내용**: UI/UX 아키텍처 섹션을 현재 프로젝트 방향(게임 스타일 UI, GUI 공유 시스템)에 맞게 업데이트