# Datacollector Codebase Structure Review and Initial Risk [[Assessment|Assessment]]

Date: 2026-04-25 20:38:01 KST
Project: Datacollector
[[Repository|Repository]]: `/Volumes/Data/project/Antigravity/Datacollector`
Knowledge Vault: `/Volumes/Data/project/Antigravity/Wiki/00_Raw`

## Summary

이 문서는 Datacollector 프로젝트의 첫 구조 파악 및 초기 코드 리뷰 결과를 정리한 기록이다.  
이번 검토의 목적은 이후 기능 개발 전에 현재 시스템의 책임 분리, 실행 흐름, 외부 의존성, 그리고 우선적으로 손봐야 할 위험 요소를 이해하는 데 있다.

현재 프로젝트는 단순한 프런트엔드 앱이 아니라, React 기반 UI와 Zustand 상태 저장소, 자율 실행 엔진, 그리고 NotebookLM MCP 및 로컬 LM을 연결하는 Express 브리지 서버가 결합된 자동화 연구 도구 형태로 구성되어 있다.

## High-Level [[Architecture|Architecture]]

전체 흐름은 아래와 같다.

`React UI -> Zustand Store -> KnowledgeEngine -> Express Bridge -> NotebookLM MCP / Local LM / GitHub / Wiki [[Storage|Storage]]`

핵심 책임 분리는 다음과 같이 이해했다.

- `src/components/AgentDashboard.tsx`
  사용자 인터페이스, 미션 시작/중지/재개, 설정 입력, 로그 표시, 수동 커밋 등 상호작용 담당
- `src/store/agentStore.ts`
  앱 전체 설정값과 실행 상태를 보관하는 단일 전역 상태 저장소
- `src/lib/engine.ts`
  큐를 소비하며 연구, 합성, 링크 추출, 다음 토픽 확장을 반복하는 자율 엔진
- `src/lib/gemini.ts`
  NotebookLM 미연결 시 사용하는 로컬 LM 프롬프트 생성 및 응답 파싱
- `src/lib/github.ts`
  결과 Markdown을 GitHub 저장소의 `00_Raw/` 경로로 업로드
- `[[Scripts|Scripts]]/mcp_bridge.mjs`
  NotebookLM MCP 서버와 통신하는 지속 프로세스형 브리지 서버

## Execution Flow

실행 흐름은 다음 순서로 이해했다.

1. 사용자가 `AgentDashboard`에서 주제를 입력하고 미션을 시작한다.
2. 주제와 설정이 `agentStore`에 기록되고 상태가 `running`으로 바뀐다.
3. `status` 변경을 감지한 UI가 `KnowledgeEngine` 싱글톤을 시작한다.
4. `KnowledgeEngine`는 큐의 첫 항목을 읽고 현재 깊이와 루트 주제를 기준으로 처리 여부를 결정한다.
5. NotebookLM 연결 상태가 좋으면 브리지 서버를 통해 리서치와 합성을 수행한다.
6. NotebookLM이 없으면 로컬 LM 프록시(`/api/lm`)를 통해 대체 연구를 진행한다.
7. 생성된 Markdown에서 위키 링크를 추출해 다음 큐를 구성한다.
8. 결과는 pending commits, completed 목록, 로컬 위키 Raw 저장소 등에 반영된다.

## Current Structure Notes

이번 시점에서 구조적으로 눈에 띈 특징은 다음과 같다.

- 상태 관리가 거의 전부 Zustand store 하나에 집중되어 있어 흐름 추적은 쉽다.
- 대신 엔진과 UI가 store를 매우 직접적으로 공유해서 결합도가 높다.
- NotebookLM 경로와 Local LM 경로가 모두 존재해 fallback 전략은 분명하다.
- 브리지 서버가 프런트엔드 백엔드이자 외부 도구 래퍼 역할까지 함께 맡고 있어 책임이 넓다.
- 문서 저장 흐름이 GitHub 업로드와 로컬 위키 저장으로 이중화되어 있다.

## Review Findings

### 1. Sensitive secrets are persisted in [[Browser|Browser]] storage

`githubToken`과 `notebookLmCookies`가 Zustand persist 설정에 포함되어 있어 브라우저 localStorage에 평문으로 저장된다.  
이 방식은 세션 쿠키나 GitHub 토큰 같은 민감 정보의 저장 위치로는 안전하지 않다.

관련 파일:

- `/Volumes/Data/project/Antigravity/Datacollector/src/store/agentStore.ts`

영향:

- 같은 브라우저 프로필을 사용하는 다른 코드나 도구가 정보에 접근할 수 있다.
- 장기적으로 토큰 유출 위험이 커진다.

### 2. Bridge server is exposed too broadly

브리지 서버는 `0.0.0.0:3002`로 열리고 CORS도 전부 허용한다.  
또한 `/api/lm`은 클라이언트가 전달한 임의의 URL로 요청을 프록시할 수 있다.

관련 파일:

- `/Volumes/Data/project/Antigravity/Datacollector/scripts/mcp_bridge.mjs`

영향:

- 로컬 개발용으로는 편하지만, 같은 네트워크 안에서 예상하지 않은 접근 통로가 될 수 있다.
- 사실상 무인증 프록시처럼 동작할 여지가 있다.

### 3. Environment portability is weak

MCP 실행 파일 경로와 위키 저장 경로가 절대경로로 하드코딩되어 있다.

관련 파일:

- `/Volumes/Data/project/Antigravity/Datacollector/scripts/mcp_bridge.mjs`

영향:

- 다른 개발자 머신, 다른 사용자 계정, 다른 운영체제에서 그대로 실행하기 어렵다.
- 배포보다는 특정 개인 작업 환경에 강하게 종속된다.

### 4. Manual handoff [[State|State]] is not fully cleared

`resolveManualNext`가 store에 함수 형태로 저장되는데, `clearState()`에서 정리되지 않는다.  
수동 합성 대기 중 reset 또는 새 미션 시작이 발생하면 상태 꼬임 가능성이 있다.

관련 파일:

- `/Volumes/Data/project/Antigravity/Datacollector/src/store/agentStore.ts`
- `/Volumes/Data/project/Antigravity/Datacollector/src/lib/engine.ts`

영향:

- 이전 미션의 대기 상태가 다음 미션에 잔존할 수 있다.
- UI 버튼 상태와 실제 엔진 대기 상태가 어긋날 수 있다.

### 5. API endpoint usage is duplicated and hardcoded

프런트엔드에는 이미 Vite 프록시가 설정되어 있지만, UI와 엔진 코드 곳곳에서 `http://127.0.0.1:3002`를 직접 호출하고 있다.

관련 파일:

- `/Volumes/Data/project/Antigravity/Datacollector/src/components/AgentDashboard.tsx`
- `/Volumes/Data/project/Antigravity/Datacollector/src/lib/engine.ts`
- `/Volumes/Data/project/Antigravity/Datacollector/vite.config.ts`

영향:

- 포트 변경이나 배포 환경 변경 시 수정 지점이 늘어난다.
- 런타임 경로 설정이 한 군데에서 관리되지 않는다.

## Validation Performed

이번 검토 중 아래 확인을 수행했다.

- 저장소 파일 구조 및 진입점 확인
- UI, store, engine, bridge, GitHub, Local LM 계층 코드 확인
- `npm run lint` 실행

검증 결과:

- TypeScript 타입체크는 현재 통과했다.

## Suggested Next Priorities

우선순위는 아래 순서가 적절하다.

1. 민감 정보 저장 방식을 localStorage 바깥으로 이동하거나 최소한 분리
2. 브리지 서버 바인딩 범위와 CORS 정책 축소
3. 절대경로를 환경변수 또는 설정 파일로 치환
4. `resolveManualNext`를 포함한 미션 종료 정리 로직 강화
5. API 베이스 URL을 단일 설정 지점으로 통합

## Working Agreement For Future Notes

사용자 요청에 따라, 앞으로 Datacollector 관련 조사/분석/리뷰 결과는 가능하면 이 지식 창고 경로에 계속 기록한다.

기본 원칙:

- 위치: `/Volumes/Data/project/Antigravity/Wiki/00_Raw`
- 파일명: `YYYY-MM-DD-<Project>_<Topic>.md` 또는 기존 저장소 관례와 유사한 읽기 쉬운 영어 제목
- 내용: 작업 목적, 파악한 구조, 핵심 발견사항, 다음 액션을 포함

## Source Files Reviewed

- `/Volumes/Data/project/Antigravity/Datacollector/README.md`
- `/Volumes/Data/project/Antigravity/Datacollector/package.json`
- `/Volumes/Data/project/Antigravity/Datacollector/vite.config.ts`
- `/Volumes/Data/project/Antigravity/Datacollector/src/main.tsx`
- `/Volumes/Data/project/Antigravity/Datacollector/src/App.tsx`
- `/Volumes/Data/project/Antigravity/Datacollector/src/components/AgentDashboard.tsx`
- `/Volumes/Data/project/Antigravity/Datacollector/src/store/agentStore.ts`
- `/Volumes/Data/project/Antigravity/Datacollector/src/lib/engine.ts`
- `/Volumes/Data/project/Antigravity/Datacollector/src/lib/gemini.ts`
- `/Volumes/Data/project/Antigravity/Datacollector/src/lib/github.ts`
- `/Volumes/Data/project/Antigravity/Datacollector/scripts/mcp_bridge.mjs`
- `/Volumes/Data/project/Antigravity/Datacollector/scripts/mcp_caller.py`
