foxminchan/BookWorm

BookWorm – 최신 마이크로서비스 시스템에 AI 에이전트를 통합하는 방법을 보여주는 데모 클라우드 네이티브 앱

정의

• 일반적인 전자상거래 스토어프론트/백오피스와 AI 기반 에이전트 제품군을 결합한 참조 구현입니다. Aspire(Microsoft의 클라우드 네이티브 애플리케이션 프레임워크)와 전체 엔터프라이즈 패턴(DDD, 수직 슬라이스 아키텍처, CQRS, 이벤트 소싱, 사가, 아웃박스/인박스 등)을 설명하기 위해 구축되었습니다.
• AI 측면에서는 대규모 언어 모델 및 임베딩에 Microsoft Foundry를 사용하고, Agent Framework를 사용하여 Model Context Protocol (MCP), A2A(에이전트 간), AG-UI(에이전트 생성 UI) 프로토콜을 통해 서로 통신할 수 있는 여러 에이전트를 오케스트레이션합니다.
• 저장소는 데모 전용으로 명시적으로 표시되어 있습니다 – 프로덕션용이 아닙니다.

주요 기능

영역	데모에 포함된 내용
아키텍처	Aspire로 구축된 클라우드 네이티브 마이크로서비스, 수직 슬라이스 아키텍처, CQRS, 이벤트 소싱, 사가 오케스트레이션, 아웃박스/인박스 패턴, 횡단 관심사를 위한 샤시.
보안	Keycloak을 사용한 인증/권한 부여, PKCE가 포함된 OAuth2 인증 코드 흐름 및 서비스 간 호출을 위한 토큰 교환 사용.
AI 통합	• LLM 호출 및 벡터 임베딩용 Microsoft Foundry • Agent Framework로 오케스트레이션되는 다중 에이전트 워크플로우 • MCP, A2A, AG-UI 프로토콜을 통한 표준화된 도구 • 정책 기반 거버넌스 및 에이전트 모니터링 • 에이전트는 대화형 UI 구성 요소(A2UI)를 생성할 수 있습니다.
API	REST 엔드포인트용 OpenAPI 사양, 이벤트 기반 계약용 AsyncAPI, Pact 기반 계약 테스트.
프론트엔드	Turborepo로 구동되는 모노레포; Next.js로 구축된 고객 스토어프론트 및 관리 백오피스, WCAG 2.1 AA 접근성 준수.
관찰 가능성 및 운영	캐싱용 FusionCache, CI/CD 파이프라인(GitHub Actions), SonarCloud 품질 게이트, SLSA-2 공급망 보호, OpenSSF Scorecard.
테스트	서비스 단위 테스트, 계약 테스트(Pact), 아키텍처 테스트, 프론트엔드 단위/컴포넌트 테스트, BDD 스타일 엔드투엔드 테스트.

기술 스택 요약

• 백엔드: .NET 8, Aspire, gRPC, Entity Framework, EventStore(이벤트 소싱), Keycloak, FusionCache.
• AI: Microsoft Foundry(LLM 및 임베딩), Agent Framework, MCP/A2A/AG-UI 프로토콜.
• 프론트엔드: Next.js(React), Turborepo, TypeScript, WCAG 준수 UI.
• 인프라: Docker, Azure Container Apps(배포), Foundry용 Azure 구독, 빠른 시작을 위한 GitHub Codespaces.
• 개발 도구: mise(버전 관리자), Buf(gRPC 코드 생성), Spec-Kit, GitHub Copilot CLI(선택 사항), Azure CLI.

로컬에서 시도하는 방법

# 저장소 클론 및 진입
git clone git@github.com:foxminchan/BookWorm.git && cd BookWorm

# 필요한 도구 설치(dotnet, bun, jdk 등)
mise install

# Foundry에 필요한 Azure 비밀 설정(자신의 ID로 교체)
aspire secret set "Azure:SubscriptionId" "<your-sub-id>"
aspire secret set "Azure:Location" "<your-location>"

# 일회성 준비(코드 생성, 컨테이너 빌드 등)
mise run prepare

# 모든 서비스 시작(Docker가 실행 중이어야 함)
mise run run

이 명령은 백엔드 서비스, Next.js 프론트엔드 및 이메일 테스트용 로컬 mail-pit 인스턴스를 시작합니다. 시작 후 곧 스토어프론트를 http://localhost:5173(또는 콘솔에 표시된 포트)에서 방문할 수 있습니다.

Azure에 배포

1. az login으로 Azure 계정에 로그인합니다.
2. aspire deploy – 스크립트가 리소스 그룹, Container Apps 환경을 만들고 Docker 이미지를 푸시합니다.
3. az containerapp show … 명령으로 공개 URL을 검색합니다.
4. 완료되면 리소스 그룹을 삭제하여 비용을 방지합니다.

유용한 경우

• 새로운 표준(MCP, A2A, AG-UI)을 사용하여 마이크로서비스 생태계에 AI 에이전트를 연결하는 방법을 배우는 경우.
• 동기(gRPC/REST) 및 비동기(이벤트 소싱, 사가) 통신을 모두 포함하는 풀스택, DDD 기반 예제를 보는 경우.
• Microsoft의 LLM 플랫폼도 사용하는 클라우드 네이티브 앱의 Azure 우선 배포를 탐색하는 경우.
• 단일 저장소에서 CI/CD, 테스트 및 보안 강화(SLSA-2, OpenSSF Scorecard)를 위한 템플릿을 얻는 경우.

제한 사항/주의 사항

• 이 프로젝트는 프로덕션 준비가 되지 않았습니다 – 강력한 확장성, 다중 지역 복원력 및 철저한 성능 튜닝이 부족합니다.
• Microsoft Foundry 구독에 의존합니다. 이 구독이 없으면 AI 구성 요소가 작동하지 않습니다.
• 일부 선택적 도구(Buf, Spec-Kit, Copilot CLI)는 핵심 데모에 필요하지 않지만 전체 코드 생성 워크플로우에는 필요할 수 있습니다.
• UI는 간단한 데모입니다. 실제 전자상거래 기능(결제, 재고 관리 등)은 스텁되거나 생략됩니다.

추가 정보

• 전체 문서는 저장소의 GitHub Wiki에 있습니다.
• 아키텍처 다이어그램(assets/BookWorm.png)은 서비스 메시 및 에이전트 상호 작용을 시각화합니다.
• 기여 지침, 행동 강령 및 이슈 템플릿이 제공되어 데모를 확장하려는 모든 사람을 지원합니다.