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

tags, date, modified

tags	date	modified
아키텍처, 에이전트, 마이크로서비스, 컨테이너, 데이터베이스, MSA	2025-07-07	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 데이터베이스 스키마

기술 구조

• 통합 인증: 사용자는 플랫폼에만 로그인합니다. 플랫폼은 각 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 공유 시스템)에 맞게 업데이트