AST 기반 규칙 추출
공개 README는 Markdown을 Remark AST로 파싱하고 문서·섹션·개념·Phase·Task·기술 노드와 source block evidence를 추출한다고 설명합니다.
고정 커밋 근거 보기 ↗
REAL PROJECT CASE
문서에서
문서에서
실제 구현으로
Markdown을 파싱하고 근거가 연결된 노드·관계를 추출해 탐색 가능한 지식 그래프로 투영하는 과정을 실제 공개 프로젝트를 기준으로 분석합니다.
AI Systems Atlas · memory_node_graphMarkdown ASTKnowledge GraphEvidenceCloudflare D1Three.js
프로젝트 사실 검증일 · source commit d8b7ca3
01 · SYSTEM BOUNDARY
처리 구조
이 사례의 핵심은 그래프 화면 자체가 아니라, 불신 입력인 Markdown에서 구조와 근거를 분리하고 저장·검색·표현 단계가 서로의 실패를 전파하지 않도록 경계를 세운 점입니다.
근거가 데이터 모델의 일부
관계를 먼저 만들고 출처를 나중에 붙이는 대신, commit·path·line 근거를 관계와 같은 생명주기로 관리해야 재인덱싱과 정정이 가능합니다.
정적 snapshot 우선 공개
공개 학습 페이지는 운영 D1과 OAuth를 직접 연결하지 않고 검증된 정적 snapshot만 배포해 장애 범위와 개인정보 노출면을 줄일 수 있습니다.
설명: 쓰기 경로는 입력 검증과 문서 단위 원자 적용을 우선하고, 읽기 경로는 저장 모델을 직접 노출하지 않고 검색·별칭·범위 예산을 적용한 snapshot을 반환합니다.
02 · WRITE & READ
데이터 흐름
문서 변경을 그래프에 반영하는 쓰기 흐름과 사용자가 검색·탐색하는 읽기 흐름을 분리하면, 인덱싱 지연이 공개 화면 전체 장애로 확산되는 것을 막을 수 있습니다.
- 입력 검증확장자·크기·SHA-256과 parser profile을 확정하고 같은 문서의 중복 적용을 차단합니다.
- 구조 추출제목 계층, 링크, 인라인 코드와 명시 패턴에서 후보 노드·관계·source block을 만듭니다.
- 문서 단위 원자 적용새 결과가 완성되기 전까지 이전 정상 그래프를 유지하고, 적용 성공 시 문서 경계를 한 번에 교체합니다.
- 검색·별칭 읽기 모델표기 변형을 canonical entity로 통합하고 FTS 결과를 문서 근거와 연결합니다.
- 범위별 snapshot전체 corpus, 저장소, 문서, 선택 노드 범위에 맞춰 노드와 관계 예산을 제한해 화면 payload를 만듭니다.
- 정적 공개 경계로그인 없는 공개 데모에는 검증 JSON만 배포하고 운영 DB·API·OAuth 토큰을 포함하지 않습니다.
03 · SCALE & FAILURE
확장·장애
노드 수보다 더 빠르게 관계 후보가 증가하므로 저장 용량, 검색 지연, 화면 투영 한도를 하나의 숫자로 다루면 안 됩니다. 각 단계에 별도 예산과 마지막 정상 결과가 필요합니다.
Parser profile 드리프트
문서 유형에 맞지 않는 규칙이 노드 폭증을 만들 수 있습니다. profile 버전과 추출 영수증을 함께 저장하고 표본 회귀를 수행합니다.
부분 적용
노드는 갱신됐지만 관계가 실패하면 유령 엔티티가 남습니다. 문서 경계 stage와 원자 교체로 이전 정상 상태를 보존합니다.
관계 폭발
모든 mention을 모든 엔티티와 연결하면 저장·화면 모두 악화됩니다. 관계 유형, hop, 중심성, 화면 예산을 각각 제한합니다.
검색 인덱스 지연
그래프 저장 이후 FTS가 늦게 반영될 수 있습니다. 저장 성공과 검색 가능 상태를 분리 관측하고 재색인 작업을 멱등 처리합니다.
공개 snapshot 불일치
데이터와 UI 배포 시점이 다르면 링크가 깨집니다. snapshot schema 버전과 digest를 배포 계약에서 함께 검증합니다.
GPU·모바일 한계
WebGL 성능이 낮은 기기에서는 노드 수·후광·자동 회전을 낮추고, 정적 목록과 검색 결과를 동일 정보의 대체 경로로 제공합니다.
04 · OPERATIONS
보안·비용
문서 파서는 입력 안의 명령을 실행하지 않고 텍스트로 취급해야 하며, 공개 그래프는 운영 인증·원문·토큰과 분리되어야 합니다. 비용은 저장량보다 재처리와 화면 밀도에서 먼저 튈 수 있습니다.
| 설계 축 | 권장 경계 | 대안과 비용 |
|---|---|---|
| 불신 Markdown | HTML·스크립트·명령형 문구를 실행하지 않고 AST 데이터로만 파싱 | 완전한 렌더링 호환성보다 안전한 추출 규칙을 우선 |
| 인증 정보 | OAuth와 저장소 토큰은 서버 런타임에만 두고 브라우저 payload에서 제거 | 클라이언트 직접 호출보다 운영 구성은 늘지만 노출면은 줄어듦 |
| 그래프 저장 | 문서·근거·관계를 원자 적용하고 재인덱싱 작업을 멱등화 | 단순 append보다 쓰기 비용이 들지만 정정과 롤백이 가능 |
| 화면 투영 | 전체 저장량과 별도로 노드·선·hop 예산을 적용한 snapshot 제공 | 완전한 그래프를 한 번에 그리지 않지만 모바일 안정성이 높아짐 |
| 공개 데모 | 운영 DB 대신 검증된 정적 JSON을 배포 | 실시간 최신성은 낮지만 API·DB·OAuth 비용과 장애를 제거 |
| 관측 | 파싱, 저장, FTS, snapshot, 렌더의 지연·실패·품질을 분리 | 단일 성공률보다 지표 수는 늘지만 장애 지점을 즉시 좁힐 수 있음 |
사실 경계: 이 페이지의 프로젝트 사실은 2026-08-28에 공개 커밋 d8b7ca377d1a6a3d8b8a40dce17f4a5f8174c879을 기준으로 검증했습니다. 설계 해석과 대안은 시스템 디자인 아틀라스가 독립적으로 작성했으며 원 프로젝트의 구현 사실로 오해해서는 안 됩니다. 검증한 소스 보기 ↗ · MIT License ↗