AutoBot 프론트엔지어 내부 구조: 개발자 가이드

AutoBot은 사용자의 데이터가 서버를 벗어나지 않는 오픈 소스, 자체 호스팅(self-hosted) AI 자동화 플랫폼입니다. GitHub: mrveiss/AutoBot-AI

AutoBot을 열었을 때 보이는 화면

AutoBot의 채팅 인터페이스는 친숙한 두 개의 패널 레이아웃으로 사용자에게 인사합니다. 왼쪽에는 대화 사이드바(conversation sidebar)가, 오른쪽에는 활성 채팅 패널(active chat panel)이 있습니다. 이러한 단순함 뒤에는 약 40개의 집중적인 Vue 단일 파일 컴포넌트(single-file components)로 구축된 풍부한 UI가 숨어 있습니다.

채팅 UI (Chat UI)

핵심 채팅 흐름은 다음과 같습니다:

• ChatView.vue
  • ChatInterface.vue
    • ChatSidebar.vue ← 대화 목록 + 검색 기능
    • ChatHeader.vue ← 모델 선택기, 설정 토글
    • ChatMessages.vue ← 스크롤 메시지 피드 │
      • MessageItem.vue ← 개별 메시지 버블 + 인용(citations)
    • ChatInput.vue ← 텍스트 영역(textarea), 첨부 파일, 전송 버튼
    • ChatTabs.vue ← 채팅(Chat) / 브라우저(Browser) / 문서(Docs) 간 전환 스위치
    • CitationsDisplay.vue ← RAG에서 가져온 인라인 출처 링크

ChatTabs.vue 컴포넌트는 핵심 지점입니다. 이 컴포넌트를 통해 사용자는 순수한 대화, 임베디드 브라우저 세션(웹 리서치용), 그리고 문서 검색 사이드바 — 모두를 동일한 뷰 내에서 전환할 수 있습니다.

지식 기반 UI (Knowledge Base UI)

AutoBot의 지식 기반은 '사용자의 데이터' 부분이 살아 숨 쉬는 곳입니다. 즉, 사용자의 데이터를 활용하는 AI가 존재하는 곳입니다.

KnowledgeView.vue는 다음 요소들을 통합합니다:

• KnowledgeBrowser: 모든 수집된 문서들의 파일 트리 스타일 탐색기(file-tree style explorer)
• KnowledgeSearch: KBSearch를 이용한 전체 텍스트 및 벡터 검색, 그리고 점수화된 결과를 렌더링하는 KnowledgeSearchResultPanel
• KnowledgeGraph / KnowledgeGraph3D: 개념들이 어떻게 연결되는지 볼 수 있는 D3 기반 엔티티 그래프(entity graph)
• KnowledgeUpload: 실시간 벡터화 진행률(VectorizationProgressModal)을 포함한 드래그 앤 드롭 방식의 문서 수집 기능
• KnowledgeMaintenance: 중복 제거, 정리 통계 및 고아 관리(orphan management)

KnowledgeView 내부 파이프라인은 30개 이상의 하위 컴포넌트로 분산되지만, 각 컴포넌트는 명확하게 정의된 책임만을 가집니다. 새로운 패널을 추가하더라도 보통 하나의 파일만 수정하면 됩니다.

컴포넌트 아키텍처 (Component architecture)

autobot-frontend/
├── src/
│ ├── components/ # 기능별 컴포넌트 트리(feature-scoped component trees)
│ │ ├── chat/
│ │ ├── knowledge/
│ │ ├── agents/
│ │ ├── browser/
│ │ ├── charts/
│ │ └── base/ # 공유 기본 요소 (버튼, 모달 등)
│ ├── views/ # 라우트 레벨 페이지 (라우트당 1개)
│ ├── stores/ # Pinia 스토어 (useChatStore, useKnowledgeStore 등)
│ ├── composables/ # 공유 반응형 로직
│ ├── design-system/ # 토큰 카탈로그 (tokens.ts — canonical token catalog)
│ ├── router/ # Vue Router 설정
│ └── styles/ # 전역 CSS + Tailwind @theme 블록
├── cypress/ # E2E 테스트(end-to-end tests)
└── package.json # Vue 3 + Vite + Tailwind CSS 4 + TypeScript

기술 스택 한눈에 보기 (Tech stack at a glance)

레이어	선택 프레임워크	언어	빌드 도구	상태 관리	스타일링	테스트
Framework	Vue 3 (Composition API)	TypeScript	Vite	Pinia	Tailwind CSS 4 (@theme tokens)	Vitest (unit) +

Cypress/Playwright (e2e) Storybook Component stories live in src/stories/ 디자인 토큰(Design tokens): 모든 색상, 간격, 반지름은 src/design-system/tokens.ts에서 가져옵니다. 이 파일이 토큰 이름의 단일 진실 공급원(single source of truth)이며; 실제 값은 @theme 블록 아래 src/assets/tailwind.css에 있습니다. // tokens.ts (요약) export const SEMANTIC_COLORS = [ { name : ' autobot-primary ' , cls : ' bg-autobot-primary text-white ' }, { name : ' autobot-secondary ' , cls : ' bg-autobot-secondary text-white ' }, { name : ' autobot-success ' , cls : ' bg-autobot-success text-white ' }, // … ] 새로운 브랜드 색상을 추가하려면 두 가지 수정이 필요합니다: 값에 대한 tailwind.css, 이름 등록을 위한 tokens.ts입니다. 끝입니다. UI 기여 방법 저장소를 실행합니다 git clone https://github.com/mrveiss/AutoBot-AI.git cd AutoBot-AI/autobot-frontend npm install npm run dev 개발 서버는 http://localhost:5173에서 시작됩니다. 시각적 컴포넌트를 작업하기 위해 백엔드가 실행될 필요가 없습니다. src/stories/에 있는 Storybook 스토리가 대부분의 UI 기본 요소(UI primitives)를 격리된 상태로 다룹니다. Storybook 탐색 npm run storybook DesignTokens.stories.ts는 한 페이지에서 전체 토큰 팔레트를 제공합니다. 실제 데이터와 연결하기 전에 컴포넌트를 격리된 상태로 보고 싶다면, 스토리가 시작하기에 적절한 장소입니다. 좋은 첫 기여 이슈 찾기 가장 빠르게 첫 번째 기여를 할 수 있는 경로는 'good first issue' + 'area: frontend' 레이블 조합입니다.

이러한 항목들은 단일 컴포넌트 또는 작은 스타일 수정에 국한됩니다. PR을 열기 전에 전체 스택을 이해할 필요가 없습니다. 일반적인 진입점은 다음과 같습니다.

• 접근성(Accessibility): ACCESSIBILITY_IMPROVEMENTS.md 문서는 채팅 및 KB UI 전반의 a11y 작업을 추적합니다.
• 디자인 토큰 누락(Design token gaps): tailwind.css에서 새로운 팔레트 항목이나 누락된 다크 모드 매핑이 있습니다.
• Storybook 커버리지: 아직 스토리가 없는 src/components/base/의 컴포넌트들입니다.
• 단위 테스트(Unit tests): src/components/**/__tests__/에 누락된 부분이 있으며, Vitest 테스트가 환영됩니다.

테스트 접근 방식:

• 단위 테스트 (npm run test:unit): Vitest + Vue Test Utils를 사용합니다. 테스트는 컴포넌트 옆의 __tests__/에 유지하십시오.
• E2E (npm run test:e2e:dev): Cypress 테스트는 cypress/에 있습니다. Vite dev server를 대상으로 실행합니다.
• 타입 검사 (Type-check): npx vue-tsc --noEmit -p tsconfig.app.json을 사용합니다. 레포지토리는 약 248개의 타입 오류(레거시 부채)가 추적된 기준선이 있으므로, PR은 오류를 추가해서는 안 됩니다. (.github/workflows/frontend-typecheck-regression.yml의 CI 검사 참조).

PR 체크리스트:

• npm run lint 통과
• npm run test:unit 통과 (또는 변경된 컴포넌트에 대한 새로운 테스트 추가)
• 기준선 대비 새로운 타입 오류 없음
• 기반(base/) 컴포넌트를 건드렸다면 Storybook 스토리 업데이트/추가

사용자 데이터. 사용자 AI. AutoBot의 프론트엔드는 프로젝트와 동일한 철학을 반영합니다. 모든 것이 로컬에서 실행되며, 제3자에게 아무것도 전송되지 않으며, 스택의 모든 부분이 검사, 확장 또는 교체할 수 있도록 개방되어 있습니다.

이 게시물이 코드베이스를 탐색하는 데 도움이 되었다면, 다음 단계는 이슈를 열거나 이미 대기 중인 것을 선택하는 것입니다. mrveiss/AutoBot-AI에서 GitHub의 좋은 첫 번째 이슈(Good first issues)를 확인하거나, 스폰서십(Sponsors), CONTRIBUTING.md 링크를 참고하세요.