aiwf

# AIWF 아키텍처 > AI 워크플로우 프레임워크의 시스템 아키텍처에 대한 종합적인 개요 [한국어](ARCHITECTURE.ko.md) | [English](ARCHITECTURE.md) ## 목차 1. [시스템 개요](#시스템-개요) 2. [아키텍처 레이어](#아키텍처-레이어) 3. [핵심 컴포넌트](#핵심-컴포넌트) 4. [데이터 흐름](#데이터-흐름) 5. [플러그인 아키텍처](#플러그인-아키텍처) 6. [보안 고려사항](#보안-고려사항) 7. [성능 아키텍처](#성능-아키텍처) 8. [확장성과 향후 확장](#확장성과-향후-확장) ## 시스템 개요 AIWF(AI 워크플로우 프레임워크)는 AI 지원 소프트웨어 개발 워크플로우를 위한 유연하고 확장 가능한 플랫폼을 제공하도록 설계된 모듈식 계층 아키텍처를 기반으로 구축되었습니다. ### 아키텍처 다이어그램 ``` ┌─────────────────────────────────────────────────────────────────┐ │ CLI 인터페이스 레이어 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ aiwf CLI │ │ aiwf-lang │ │ 훅 │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ └─────────┼─────────────────┼─────────────────┼──────────────────┘ │ │ │ ┌─────────┼─────────────────┼─────────────────┼──────────────────┐ │ │ 코어 엔진 레이어 │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ │ │ 명령어 │ │ 리소스 │ │ 상태 │ │ │ │ 프로세서 │ │ 로더 │ │ 관리자 │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ │ │ 템플릿 │ │ 플러그인 │ │ 토큰 │ │ │ │ 엔진 │ │ 시스템 │ │ 관리자 │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ └─────────┼─────────────────┼─────────────────┼──────────────────┘ │ │ │ ┌─────────┼─────────────────┼─────────────────┼──────────────────┐ │ │ 저장소 및 영속성 레이어 │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ │ │ 파일 │ │ JSON │ │ Git │ │ │ │ 시스템 │ │ 저장소 │ │ 통합 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ ┌─────────▼─────────────────▼─────────────────▼──────────────────┐ │ AI 통합 레이어 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 페르소나 │ │ 압축 │ │ 평가 │ │ │ │ 관리자 │ │ 엔진 │ │ 시스템 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## 아키텍처 레이어 ### 1. CLI 인터페이스 레이어 AIWF와의 모든 사용자 상호작용을 위한 진입점입니다. - **aiwf CLI**: Commander.js로 구축된 주요 명령줄 인터페이스 - **aiwf-lang**: 국제화를 위한 언어 관리 CLI - **훅**: Git 훅 및 시스템 통합 지점 ### 2. 코어 엔진 레이어 AIWF 기능의 핵심입니다. - **명령어 프로세서**: 명령어 라우팅 및 실행 - **리소스 로더**: 번들 및 사용자 리소스 관리 - **상태 관리자**: 워크플로우 상태 및 전환 처리 - **템플릿 엔진**: 프로젝트 템플릿 처리 - **플러그인 시스템**: 확장성 지원 - **토큰 관리자**: AI 토큰 사용량 추적 및 최적화 ### 3. 저장소 및 영속성 레이어 모든 데이터 저장 및 검색을 관리합니다. - **파일 시스템**: 직접 파일 작업 및 캐싱 - **JSON 저장소**: 구조화된 데이터 영속성 - **Git 통합**: 버전 관리 시스템 통합 ### 4. AI 통합 레이어 지능형 기능과 AI 지원을 제공합니다. - **페르소나 관리자**: AI 동작 사용자 정의 - **압축 엔진**: AI 모델을 위한 컨텍스트 최적화 - **평가 시스템**: 코드 및 응답 품질 평가 ## 핵심 컴포넌트 ### 리소스 로더 리소스 로더는 개발 및 프로덕션 환경 모두에서 리소스를 관리하는 중요한 컴포넌트입니다. ```javascript // 리소스 로딩 우선순위 1. 사용자 리소스 (~/.aiwf/) 2. 프로젝트 리소스 (./.aiwf/) 3. 번들 리소스 (npm 패키지) ``` 주요 기능: - 동적 리소스 검색 - 폴백 메커니즘 - 템플릿 및 페르소나 관리 - 개발 중 핫 리로딩 ### 상태 관리자 정교한 워크플로우 기반 상태 관리 시스템을 구현합니다. ```javascript // 상태 구조 { "version": "1.0.0", "lastUpdated": "ISO-8601 타임스탬프", "workflow": { "currentPhase": "development", "currentTask": "task-id", "transitions": [] }, "tasks": { "task-id": { "status": "in-progress", "dependencies": [], "priority": 0.8 } } } ``` 기능: - 의존성 추적 - 우선순위 계산 - 순환 의존성 감지 - 상태 검증 - 전환 관리 ### 명령어 프로세서 모듈식 설계로 명령어 라우팅 및 실행을 처리합니다. ```javascript // 명령어 구조 export default async function commandName(options) { // 검증 // 실행 // 상태 업데이트 // 결과 포맷팅 } ``` ### 템플릿 엔진 AIWF 통합이 내장된 프로젝트 스캐폴딩을 제공합니다. 지원되는 템플릿: - `api-server`: TypeScript를 사용한 Express.js API - `npm-library`: Rollup을 사용한 NPM 패키지 - `web-app`: Vite를 사용한 React 애플리케이션 ### 플러그인 시스템 훅 기반 아키텍처를 통해 확장성을 지원합니다. ```javascript // 플러그인 인터페이스 export interface AIWFPlugin { name: string; version: string; hooks: { beforeCommand?: (command: string, args: any) => void; afterCommand?: (command: string, result: any) => void; beforeStateChange?: (oldState: State, newState: State) => State; afterStateChange?: (state: State) => void; }; } ``` ## 데이터 흐름 ### 명령어 실행 흐름 ``` 사용자 입력 → CLI 파서 → 명령어 프로세서 → 명령어 구현 ↓ ↓ 토큰 추적 ← 상태 업데이트 ← 결과 처리 ← 실행 ↓ 사용자 출력 ``` ### 리소스 로딩 흐름 ``` 리소스 요청 → 사용자 리소스 확인 → 발견? → 반환 ↓ 미발견 프로젝트 리소스 확인 → 발견? → 반환 ↓ 미발견 번들 리소스 로드 → 반환 ``` ### 상태 관리 흐름 ``` 명령어 실행 → 사전 검증 → 상태 잠금 → 상태 업데이트 ↓ 사후 검증 ↓ 구독자 알림 ↓ 잠금 해제 ``` ## 플러그인 아키텍처 AIWF의 플러그인 시스템은 코어 코드를 수정하지 않고도 기능을 확장할 수 있게 합니다. ### 플러그인 로딩 1. 다음 위치에서 플러그인 스캔: - `~/.aiwf/plugins/` - `./node_modules/aiwf-plugin-*/` - 명시적 플러그인 경로 2. 플러그인 구조 검증 3. 훅 등록 4. 플러그인 초기화 ### 훅 포인트 - **라이프사이클 훅**: `init`, `destroy` - **명령어 훅**: `beforeCommand`, `afterCommand` - **상태 훅**: `beforeStateChange`, `afterStateChange` - **리소스 훅**: `beforeResourceLoad`, `afterResourceLoad` ## 보안 고려사항 ### 입력 검증 모든 사용자 입력은 처리 전에 검증됩니다: - 명령어 인수 살균 - 경로 순회 방지 - 인젝션 공격 방지 ### 리소스 격리 - 사용자 리소스는 시스템 리소스와 격리됨 - 샌드박스 템플릿 실행 - 제한된 파일 시스템 접근 ### 토큰 보안 - 토큰 수는 로컬에만 저장 - 토큰 추적에 민감한 데이터 없음 - 구성 가능한 개인정보 설정 ## 성능 아키텍처 ### 최적화 전략 1. **지연 로딩**: 명령어와 리소스를 필요시 로드 2. **캐싱**: 자주 접근하는 리소스를 메모리에 캐시 3. **병렬 처리**: 독립적인 작업을 동시에 실행 4. **증분 업데이트**: 변경된 상태 부분만 업데이트 ### 메모리 관리 - 템플릿을 위한 리소스 풀링 - 자동 캐시 제거 - 메모리 사용량 모니터링 - 가비지 컬렉션 최적화 ### 성능 모니터링 내장 성능 추적: - 명령어 실행 시간 - 리소스 로딩 시간 - 상태 작업 메트릭 - 토큰 사용 효율성 ## 확장성과 향후 확장 ### 계획된 확장 1. **클라우드 동기화**: 기기 간 상태 동기화 2. **팀 협업**: 공유 워크플로우 및 상태 3. **커스텀 AI 모델**: 자체 호스팅 모델 지원 4. **고급 분석**: 상세한 생산성 메트릭 ### 확장 포인트 - 사용자 정의 명령어 개발 - 새로운 템플릿 유형 - 추가 AI 페르소나 - 대체 저장소 백엔드 - 사용자 정의 압축 전략 ### API 안정성 AIWF는 시맨틱 버전 관리를 따릅니다: - v1.0.0부터 코어 API 안정화 - 플러그인 API는 별도로 버전 관리 - 주요 변경사항에 대한 사용 중단 알림 - 주요 버전에 대한 마이그레이션 가이드 ## 결론 AIWF의 아키텍처는 모듈식, 확장 가능, 고성능으로 설계되었습니다. 계층화된 접근 방식은 관심사의 분리를 보장하며, 플러그인 시스템은 코어 안정성을 손상시키지 않으면서 사용자 정의를 가능하게 합니다. 이 아키텍처는 역호환성을 유지하면서 현재 기능과 향후 확장을 모두 지원합니다.