Genesys Archivist

Genesys Cloud Architect 플로우와 해당 플로우가 의존하는 모든 리소스를 캡처한 다음, 그 캡처로부터 비즈니스 및 기술 문서를 생성합니다.

두 가지 소비자, 두 가지 보장:

Archivist는 해당 마이그레이션 서버를 구축하지 않습니다. 그 서버가 소비할 데이터 계약을 보장할 뿐입니다.

상태

구현 전 단계. Phase 0은 실행되지 않았습니다. 설계와 계획은 완료되었으며, 아직 프로덕션 코드는 존재하지 않습니다.

한 문단으로 보는 아키텍처

두 단계가 단단한 경계로 분리되어 있습니다. 1단계(캡처) 는 Genesys와 통신하는 유일한 코드로, 모든 유형의 모든 플로우를 발견하고, 정의를 가져오고, 리소스 참조 그래프를 닫힐 때까지 순회하고, 바이너리 자산을 다운로드하고, 불변의 콘텐츠 해시 캡처 번들을 봉인합니다. 2단계(문서화) 는 소켓을 열지 않습니다 — 번들을 읽고 Markdown, SVG 다이어그램, PDF를 생성하며, 중간에 AI 내레이션이 포함됩니다. 따라서 문서를 다시 렌더링하는 데는 Genesys API 호출 비용이 전혀 들지 않으며, 번들은 일회용 캐시가 아닌 공개된 계약입니다.

flowchart TD
    A["AI client"] -->|MCP STDIO| B["MCP adapter"]
    C["archivist CLI"] --> D["Application service"]
    B --> D
    D --> E["Genesys source provider"]
    E --> F["Genesys Cloud"]
    D --> G["Capture bundle (sealed, immutable)"]
    G --> H["Normalize, analyze, document"]
    H --> I["Markdown + diagrams + PDF"]
    G --> J["Future migration server"]

시작하기

npm install
npm run verify        # format + lint + typecheck + test + schema validation

그런 다음 순서대로 읽으세요:

1. CLAUDE.md — 여기에서 코드를 작성하려는 모든 사람(인간 또는 에이전트)을 위한 오리엔테이션.

2. AGENTS.md — 양보할 수 없는 경계. 하나라도 위반하면 릴리스가 차단됩니다.

3. 설계 명세 — 무엇을 왜 구축하는지. 섹션 2는 아래의 번호가 매겨진 청사진 문서와 다른 지점을 나열합니다.

4. Plan 1: Foundation — Genesys 접근이 필요 없는 12개의 작업별 TDD 태스크.

5. Phase 0 스파이크 — 다른 모든 것을 진행 가능하게 만드는 go/no-go 게이트.

Phase 0은 go/no-go 게이트입니다

Genesys 어댑터를 구축하기 전에 비프로덕션 조직을 대상으로 다음을 입증하세요: 읽기 전용 OAuth 클라이언트가 페이지와 디비전에 걸쳐 필요한 모든 플로우 유형을 열거할 수 있고, 소스 경로가 게시된 플로우를 충실히 로드하고 내보낼 수 있으며, 프롬프트 오디오가 읽기 전용으로 다운로드되고, 변경 권한이 필요 없다는 것을 입증하세요. 스파이크 10개, 킬 기준 12개. docs/spikes/를 참조하세요.

네 가지 소스 경로가 경쟁 중입니다 — Platform API, Archy CLI, Architect Scripting SDK, 수동 YAML. 어느 것이 승리할지는 가정이 아닌 경험적 결과입니다.

리포지토리 구조

apps/cli               archivist CLI
apps/mcp-server        genesys-archivist MCP STDIO server
packages/domain        contracts and DTOs. Pure: no I/O, no SDK types
packages/application   use cases, run state machines, policy
packages/composition   the one place adapters are wired to interfaces
packages/...           adapters, capture, analysis, documentation, rendering, narrative
schemas/               versioned JSON Schema contracts
fixtures/              sanitized test fixtures. Never real customer configuration
docs/                  blueprint, design spec, plans, ADRs, spikes

의존성 방향은 관례가 아닌 ESLint로 강제됩니다: domain은 아무것도 임포트하지 않고, application은 domain만 임포트하며, apps/*는 얇게 유지됩니다.

절대 커밋하지 말 것

bundles/, derived/, documentation/, spike-evidence/, 또는 모든 .wav / .mp3 파일. 캡처 번들은 restricted로 분류됩니다 — 엔드포인트 URL, DID, 라우팅 로직, 고객 PII를 포함할 수 있는 데이터 테이블 행, 프롬프트 오디오를 포함하기 때문입니다. 이 중 하나라도 추적되면 CI가 빌드를 실패시킵니다.

용어

대상은 Genesys Cloud CX이며, IVR 작성 제품은 Architect입니다.

플로우에는 flowId와 같은 식별자와 버전이 있습니다. 큐, 프롬프트, 데이터 액션, 스케줄, 재사용 가능한 플로우에도 식별자가 있습니다. 이것들은 비밀 API 키가 아닙니다. Genesys OAuth client_id와 client_secret은 통합을 인증하며 관련된 유일한 비밀입니다. 이 도구는 숨겨진 비밀을 열거하거나, OAuth 클라이언트 비밀을 복구하거나, 비밀번호를 스크래핑하거나, Genesys 권한을 우회하지 않습니다.

첫 프로덕션 릴리스의 비목표

• Genesys 플로우 편집, 게시, 삭제 또는 가져오기

• 고객 비밀 복구 또는 나열

• 실시간 발신자 데이터, 녹음, 대화록 또는 과거 실행 데이터 읽기

• 캡처된 데이터에 대한 쿼리 또는 Q&A 도구

• 원격 HTTP 호스팅, git/PR 자동화 또는 스케줄링 데몬

• 구성에서 추론할 수 없는 비즈니스 의도 주장

청사진 문서

원래의 인수인계 문서. 설계 명세가 재정의하지 않는 한 여전히 적용됩니다.