---
id: connectai-architecture-overview
title: "ConnectAI 아키텍처 개요"
category: "Architecture"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["Astra", "ConnectAI", "feature-based architecture", "전체 구조", "모듈 아키텍처", "제2뇌 OS"]
duplicate_of: ""
source_trust_level: "S"
confidence_score: 0.95
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["architecture", "connectai", "feature-based", "layering", "overview"]
raw_sources: ["ConnectAI/src/extension.ts", "ConnectAI/src 트리(308 TS 파일)", "ConnectAI/package.json", "ConnectAI/src/core/services.ts"]
applied_in: ["ConnectAI"]
github_commit: ""
---

# [[ConnectAI 아키텍처 개요]]

## 🎯 한 줄 통찰 (One-line insight)
ConnectAI(Astra)는 "로컬 LLM 을 두뇌로 쓰는 VS Code 확장형 자기진화 지식 OS"이며, **기능별 폴더 경계 + 얇은 entry point + 핵심 인프라(core) 위에 도메인(features)을 쌓는 계층형 모듈 아키텍처**로 308개 파일을 조직한다 [S1][S2].

## 🧠 핵심 개념 (Core concepts)
1. **Feature-based 구조:** `src/features/` 아래 각 폴더가 독립 기능(stocks, calendar, company, datacollect, devilAgent…). 기능 간 결합을 최소화하고, 공통 인프라만 `core/`/`lib/` 에서 공유 [S2].
2. **계층 분리:** `core`(인프라) → `lib`/`memory`/`retrieval`/`intelligence`(역량) → `features`(기능) → `extension.ts`(조립). 아래 계층은 위를 모른다 [S2].
3. **얇은 entry point:** `extension.ts` 의 `activate()` 는 *조립과 등록만* 한다 — 객체 생성, 의존성 주입, 명령 등록, 워처 시작. 로직은 전부 모듈에 위임 [S1].
4. **의존성 주입:** 생성자에 옵션 객체로 협력자를 주입(`new AgentExecutor(context, { lmStudioStreamer, approvalQueue, ... })`) — 테스트·교체 용이 [S1].
5. **싱글톤 인프라:** 프로세스 전역이 자연스러운 자원(`lockManager`, `actionQueue`)은 모듈 싱글톤으로 export [S1].

## 🧩 추출된 패턴 (Extracted patterns)
- **God-class 분해:** 거대해지는 orchestrator(`agent.ts`)를 `handlePrompt/`, `llm/`, `actions/`, `multiAgent/`, `sessions/` 하위 모듈로 쪼개 함수 단위로 추출하고, orchestrator 는 이들을 호출만 한다 [참조: [[Agent 오케스트레이터 분해]]].
- **인터페이스 우선 서비스:** `IAIService`/`IBrainService` 인터페이스를 두고 구현(`AIService`)을 분리 — 엔진 폴백 같은 정책을 구현체에 캡슐화 [S3].
- **자기등록 핸들러:** slashRouter 에 핸들러가 side-effect import 로 자기 등록 — 새 명령 추가 시 중앙 등록표를 건드리지 않음 [S1].
- **부트스트랩 분리:** 활성화 시 필요한 초기화(brain 디렉터리, 임베딩 감지, 기능 인벤토리)를 `extension/*Bootstrap.ts` 로 분리해 entry point 를 얇게 유지 [S1].
- **disposable 수명 관리:** 생성한 모든 자원을 `context.subscriptions.push(...)` 로 등록해 확장 종료 시 일괄 정리 [S1].

## 📖 세부 내용 (Details)
### 디렉터리 지도 (역할별)
- **core/** — 횡단 인프라: `lock`, `queue`, `transaction`, `errors`, `errorHandler`, `services`(AI/Brain 서비스), `session`, `events`, `health`, `telemetry`, `statusBar`.
- **memory/** — 5계층 인지 메모리(Short/Long/Project/Procedural/Episodic) + `distillation`. → [[5계층 메모리 시스템]].
- **retrieval/** — RAG 파이프라인: `chunker`, `scoring`(TF-IDF), `embeddings`, `brainIndex`, `contextBudget`, rerank 류. → [[RAG 검색 파이프라인]].
- **intelligence/** — 검증·자기평가: `criticAgent`, `confidenceEngine`, `correctionLoop`, `epistemicGuardBlock`, `knowledgeValidation`. → [[Intelligence 검증 레이어]].
- **lib/contextBuilders/** — 프롬프트에 들어갈 컨텍스트 블록을 조립하는 순수 함수 모음(메모리·프로젝트·일정·자기인식 등 30+개).
- **features/** — 도메인 기능. 각자 `index.ts`(공개 API) + store + handler + prompt 로 구성되는 경향.
- **agent/** + **agents/** — 에이전트 실행 세부와 다중 에이전트 워크플로 매니저.
- **integrations/** — 외부 연동(telegram).
- **sidebar/** + **sidebarProvider.ts** — 웹뷰 UI 와 메시지 핸들러.
- **system/**, **lmstudio/**, **scaffolder/**, **skills/** — 시스템 사양 탐지, LM Studio SDK 수명관리, 프로젝트 스캐폴딩, 스킬 로딩.

### 제어 흐름 (한 턴의 처리)
1. 웹뷰(사이드바)에서 사용자 입력 → `sidebar/chatHandlers` → `AgentExecutor`.
2. `agent/handlePrompt/*` 가 컨텍스트 블록(메모리·RAG·프로젝트·일정)을 조립.
3. 모델 라우팅: 클라우드 prefix 면 provider 어댑터, 아니면 로컬 엔진(LM Studio/Ollama). → [[LLM 프로바이더 추상화]].
4. 스트리밍 응답 → 후처리(sanitize, devil rebuttal) → post-answer hooks(critic 검수, 교정 캡처).
5. 세션 종료 시 메모리 추출/증류, 성장 사이클 워처가 폐루프로 학습.

### 빌드/런타임
- esbuild 단일 번들(`out/extension.js`), `vscode` external. 런타임 의존성은 `@lmstudio/sdk`, `pdf-parse` 둘뿐 — 나머지는 native API(fetch 등)로 자급 [S2].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **단일 거대 agent.ts(1681줄):** 분해를 했음에도 orchestrator 가 여전히 크다. 이는 "한 턴의 제어 흐름을 한 곳에서 읽을 수 있게" 하려는 의도적 트레이드오프 — 세부는 추출하되 흐름의 골격은 남긴다.
- **features 간 결합:** 일부 기능(company, stocks)은 텔레그램·시트 등 여러 통합을 동시에 참조해 완전 독립은 아니다. core/lib 를 통한 간접 결합으로 완화.

## 🛠️ 적용 사례 (Applied in summary)
- `ConnectAI/src/extension.ts` 의 `activate()` 전체가 "얇은 조립 entry point" 의 교과서적 예 — 25개+ 모듈을 생성·주입·등록하지만 비즈니스 로직은 0 [S1].

## 💻 코드 패턴 (Code patterns)
```typescript
// activate(): 조립과 등록만 — 로직은 모듈에 위임 (src/extension.ts 발췌)
export async function activate(context: vscode.ExtensionContext) {
    await ensureDefaultBrainConfigured();          // 부트스트랩 분리
    void ensureEmbeddingConfigured(context);       // 비차단 best-effort
    initAstraPathResolver(context);

    const lmStudioClient = new LMStudioClient(getConfig().ollamaUrl);
    const agent = new AgentExecutor(context, {     // 생성자 의존성 주입
        onStreamLifecycle: { start: () => lifecycle.onStreamStart(), end: () => lifecycle.onStreamEnd() },
        lmStudioStreamer, approvalQueue,
    });
    const provider = new SidebarChatProvider(context.extensionUri, context, agent, { lifecycle, /* ... */ });

    context.subscriptions.push(                     // 수명 관리: 종료 시 일괄 dispose
        vscode.commands.registerCommand('g1nation.openChat', () => provider.openAsPanel(vscode.ViewColumn.Three)),
        ...registerProviderCommands(context, { getProvider: () => provider }),
    );
}
```

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
- **관련 개념:** [[VSCode 확장 구조와 생명주기]], [[의존성 주입과 서비스 인터페이스]], [[Agent 오케스트레이터 분해]], [[모듈 시스템과 프로젝트 구성]]
- **참조 맥락:** 로컬 LLM 이 새 기능을 "어느 계층/폴더에 어떤 형태로" 추가할지 판단할 때 최상위 지도로 참조.

## 📚 출처 (Sources)
- [S1] ConnectAI/src/extension.ts — activate/deactivate, 조립·주입·등록·부트스트랩
- [S2] ConnectAI/src 디렉터리 트리(308 TS 파일) + package.json — 계층/번들 구성
- [S3] ConnectAI/src/core/services.ts — IAIService/IBrainService 인터페이스 우선 설계

## 📝 변경 이력 (Change history)
- 2026-06-13: ConnectAI 전체 코드 분석 기반 초안 생성.