Funnel

Funnel은 긴 PDF 기반 학습을 다시 이어갈 수 있도록 설계된 local-first 공유 학습 작업공간입니다. book과 concept으로 구분되는 Workspace 위에 동일한 Shared wiki를 두고, 읽기/요약/추론이 남긴 맥락을 추적 가능한 지식 구조로 보존합니다.

Funnel이 하는 일

기술 문서를 처음부터 끝까지 읽어도, 시간이 지나 다시 돌아왔을 때 같은 추론 경로를 다시 만들기 어렵다는 점이 핵심 문제였습니다. Funnel은 “한 번의 대화 결과”가 아니라 “근거가 붙은 작업 이력”을 남기는 방향으로 문제를 풀어냅니다.

• 작업은 Workspace 단위로 정리됩니다.
• 원본 자료와 처리 결과는 Materials로 관리하고, 문서 구조는 Section 단위로 정합합니다.
• 핵심 지식은 Wiki node로 축적하고, 질문·추론은 GroundingContract를 통해 근거를 남깁니다.
• 학습을 멈춘 지점은 Re-entry 상태로 저장해 다음 진입점으로 복구합니다.

핵심 개념

• Workspace: 사용자의 학습 작업 범위를 나타내는 상위 단위입니다.
• Book workspace: PDF 업로드가 기반이 되는 Workspace입니다.
• Concept workspace: 사용자가 지식 연결을 설계하는 사용자 중심 Workspace입니다.
• Shared wiki: Book/Concept workspace가 함께 사용하는 Wiki graph입니다.
• Materials: PDF 원본, 추출 텍스트, 처리 산출물 및 관련 작업 아티팩트를 다루는 저장·처리 영역입니다.
• Section: PDF 내용의 구획 단위로, Wiki node를 만들고 검색·근거 추적을 연결하는 기준점입니다.
• Wiki node: 텍스트, 개념, 근거 링크, 다음 행동 제안을 담는 지식 단위입니다.
• GroundingContract: 질의/응답이 어떤 근거를 사용했는지 구조적으로 기록하는 계약 데이터입니다.
• Re-entry: 작업을 이어갈 때 복원되는 진행 상태와 컨텍스트입니다.

사용자가 보는 흐름

1. book Workspace를 만들고 PDF를 업로드하면 pipeline이 Materials를 처리합니다.
2. 처리된 결과는 Section 단위로 정리되고, Shared wiki로 반영될 수 있는 지식 덩어리로 변환됩니다.
3. Wiki page에서 핵심 Wiki node를 열람하고, 관계를 따라 다른 Wiki node로 확장합니다.
4. 공부를 중단하면 Re-entry가 저장되고, 다음 진입 시 이어갈 위치와 상태를 복원합니다.
5. 질의는 /api/wiki/query 흐름에서 GroundingContract 형태로 반환되어, 응답 근거를 따라가 확인할 수 있습니다.

이 흐름에서 사용자가 보는 화면은 단순한 메모 앱이 아니라 “근거가 붙은 학습 상태”입니다.

전체 구조

flowchart LR
    User["사용자"] --> Frontend["React UI<br/>Home · Graph · Wiki"]
    Frontend --> API["FastAPI<br/>Workspace / Wiki / Query"]
    API --> PG[("PostgreSQL 17 + pgvector<br/>workspaces, wiki_*, material_*, query plane")]
    API --> Worker["Material worker<br/>job queue 처리"]
    Worker --> Uploads["data/uploads<br/>작업본"]
    Worker --> R2["Cloudflare R2<br/>원본 · 아카이브"]
    Worker --> PG
    API --> AI["Task runner<br/>pydantic-ai · LangGraph"]
    AI --> Trace["RunTrace JSONL<br/>근거 분석 기록"]
    AI --> PG
    PG --> Frontend

Loading

• API와 Worker는 별도 프로세스로 분리되어 처리량과 복구 동작이 분리됩니다.
• 원본 산출물은 data/uploads와 R2로 분리되고, 정규 상태는 PostgreSQL 도메인 테이블이 중심이 됩니다.
• UI는 조회/편집/탐색을 수행하고, 근거 기반 질의 결과는 GroundingContract로 저장되어 추적성이 보존됩니다.

화면 예시

Home	Workspace

프로젝트 구성

Frontend

• frontend/src/app의 라우팅(surface)에서 Home, Graph, Wiki, Settings, readiness 진입점을 제공합니다.
• frontend/src/features/graph는 Workspace graph에서 node 간 연계를 시각화합니다.
• frontend/src/features/wiki는 Wiki page/목록/편집/근거 노출을 담당합니다.
• API는 frontend/src/lib/api에서 관리해 화면 계층에서 직접 fetch를 사용하지 않도록 구성됩니다.

Backend

• backend/app/api/routes에서 workspace, wiki, query, material, metrics, eval, traces, settings 등 요청 경계를 제공합니다.
• backend/app/domain/services에서 Workspace, Wiki, Materials, grounding, Re-entry 관련 도메인 변경을 담당합니다.
• backend/app/ai는 task spec/topology/traced task runner 기반으로 질의 실행 계획과 근거 산출을 일관되게 처리합니다.
• backend/material_commands/worker_main.py가 PostgreSQL job 큐의 pending → running → completed|failed 흐름을 처리합니다.

저장소에서 볼 위치

경로	역할
frontend/src	앱 진입점, 상태 관리, 페이지·기능 모듈
backend/app	FastAPI API, 도메인 서비스, AI task/grounding 계층
backend/material_pipeline	PostgreSQL 기반 pipeline repository 및 SQL migration
backend/material_commands	Material worker 진입점

주요 동작 정리

• book Workspace: PDF 업로드가 시작점이며 Materials 파이프라인의 결과가 Shared wiki 기반 지식으로 이어집니다.
• concept Workspace: 사용자 중심의 노드 조직이 기본이며, Shared wiki를 통해 Book workspace와 연결된 동일한 지식 graph를 봅니다.
• Section 중심 이해: Section은 Materials에서 도출되는 근거 단위이고, Wiki node는 이 근거를 조직적으로 연결합니다.
• Re-entry: 이전 세션 맥락(진행 상태, 추천 다음 행동, 최근 근거)을 되돌려 주어 재진입 비용을 줄입니다.
• GroundingContract: AI 응답의 신뢰 경로를 유지해 근거 다시 확인, 응답 출처 추적, 다음 학습 분기 제안의 정합성 확인에 사용됩니다.

현재 범위와 진행 중인 항목

작동 범위는 다음 항목들입니다.

• book/concept Workspace 생성과 Shared wiki 기반 노드 관리
• chunked upload 기반 Materials 처리 및 Section 중심 ingest
• Wiki page 조회/편집, Workspace graph 조회
• Re-entry 상태 계산과 이어 학습 진입
• /api/wiki/query 기반 grounded Ask의 evidence/next action 기록

진행 중 또는 제한된 영역은 다음과 같습니다.

• concept에서 기존 Wiki node 참조를 추가·제거하는 기능은 API가 우선 반영되어 있으며, 기본 UI 경로는 부분적으로 완성된 상태입니다.
• image-only PDF, 심한 OCR 손상, 복잡한 다단 레이아웃은 처리 등급이 낮아 degraded 또는 failed로 분기될 수 있습니다.
• 다중 사용자 동기화 및 고도화된 협업 권한 모델은 현재 범위 밖입니다.

더 알아보기

• Architecture
• Backend Domain
• Request Flows
• Frontend User Flows
• Current Status