Archify는 코드베이스나 시스템 아키텍처를 인터랙티브한 시각적 다이어그램으로 변환하기 위한 Node.js 기반의 렌더링 및 검증 시스템입니다. 이 도구는 개발자가 텍스트 기반의 설명을 입력하면, 이를 타입이 지정된 JSON IR(Intermediate Representation)로 변환한 뒤, 결정론적(deterministic) 방식으로 고품질의 HTML/SVG 다이어그램을 생성합니다.

핵심 방법론 및 기술적 상세

Archify의 아키텍처는 에이전트(Agent) 중심의 생성 단계와 엄격한 검증(Validation) 단계를 결합한 파이프라인을 따릅니다.

1. Typed JSON IR 기반 생성: 에이전트는 입력된 시스템 요구사항을 토대로 정형화된 JSON IR을 생성합니다. 이는 단순히 그림을 그리는 것이 아니라, 노드와 관계를 명시적인 데이터 구조로 정의하여 일관성을 보장합니다.
2. 원자적 검증(Atomic Validation): 렌더링 전 단계에서 스키마, 레이아웃 규칙, HTML/SVG 구조, 경로(route) 및 라벨 간격 등을 검증합니다. 모든 검증을 통과해야만 결과물이 생성되며, 실패 시에는 단순히 에러를 뱉는 대신 diagnostics[] 객체를 통해 구체적인 수리 방안(supportedFixes)을 제공합니다.
3. 레이아웃 제어: 일반적인 자동 레이아웃(auto-layout) 도구와 달리, 에이전트가 계층, 간격, 경로, 강조 사항을 결정하는 '레이아웃 판단' 체계를 가집니다. 이를 통해 복잡한 경로가 교차할 때 결정론적인 렌더링을 수행합니다.
4. Before/Delta/After 분석: 아키텍처 변경 사항을 추적하기 위해 두 개의 검증된 JSON 스냅샷을 비교하는 기능을 제공합니다. 이는 node archify/bin/archify.mjs compare architecture base.json head.json 명령을 통해 변경된 사실(added, removed, changed, moved, rerouted)을 정확히 분석합니다.

주요 기능 및 특징

• 5가지 다이어그램 유형: Architecture(구성 요소), Workflow(CI/CD, 런북), Sequence(API 호출, 추적), Data Flow(데이터 라인업, PII), Lifecycle(상태 변경, 재시도)을 지원합니다.
• 상호작용성: 생성된 다이어그램은 단순한 정적 이미지가 아니며, 노드 검색, 업스트림/다운스트림 경로 추적(Tracing), 역할 비교(Semantic lens), Guided Stories 재생이 가능합니다.
• 확장성 및 호환성: Cursor, Claude Code, Codex CLI, OpenCode 등 다양한 에이전트 환경에서 Skill로 추가하여 사용할 수 있으며, 로컬 파일 시스템에서 안정적인 렌더링을 제공합니다.
• 결정론적 상태 유지: preview 모드를 통해 소스 코드를 감시하다가, 유효한 변경 사항이 있을 때만 마지막으로 검증된(last-good) 상태를 갱신합니다.

기술 스택 및 환경

• Node.js 기반: 고성능 런타임 환경에서 동작하며, npx를 통한 즉각적인 실행이 가능합니다.
• 포트 유지: 127.0.0.1 루프백을 사용하여 외부 통신 없이 로컬에서 안전하게 프리뷰를 수행합니다.
• 환경 설정: $ARCHIFY_UPDATE_CHECK_DISABLED=1$ 설정을 통해 네트워크 연결을 완전히 차단하고 오프라인 환경에서도 동일한 검증 로직을 유지할 수 있습니다.

이 시스템은 범용적인 드로잉 툴이나 단순 Mermaid 문법이 아니며, 엔지니어링 의도를 정확한 기계적 표현으로 변환하여 기술적 문서를 문서화하고 검증하는 데 최적화된 도구입니다.