시스템 디자인SYSTEM DESIGN
학습 시작하기 →
REAL PROJECT CASE

문서에서
실제 구현으로

Markdown 파일을 읽어 제목과 링크를 찾고, 노드와 관계로 저장한 뒤 검색·그래프 화면에 전달하는 과정을 살펴봅니다. 공개 데모에서 확인할 수 있는 동작과 운영자가 설명한 구현, 이 페이지의 설계 제안을 구분했습니다.

AI Systems Atlas · memory_node_graph
Markdown ASTKnowledge GraphEvidenceCloudflare D1Three.js

화면 동작은 라이브 그래프에서 확인할 수 있으며, 내부 처리 구조는 운영자 설명과 설계 제안으로 나누어 표시합니다.

01 · SYSTEM FLOW

처리 구조

파일을 받으면 먼저 형식과 크기를 확인하고, 제목·링크·코드 표기를 읽어 노드와 관계 후보를 만듭니다. 저장이 끝난 결과만 검색과 그래프 화면에 전달해 파싱 실패가 기존 화면을 망가뜨리지 않도록 구성했습니다.

설계 판단

출처 위치를 관계와 함께 관리

관계를 만든 뒤 출처를 별도로 붙이면 문서가 바뀔 때 오래된 연결이 남기 쉽습니다. 문서 경로와 줄 위치를 관계와 함께 갱신하면 재처리와 정정 범위를 좁힐 수 있습니다.

설계 제안

정적 그래프 우선 공개

로그인 없는 공개 화면에는 운영 데이터베이스를 직접 연결하지 않고 읽기 전용 JSON을 배포할 수 있습니다. 실시간성은 낮아지지만 인증 정보 노출과 운영 장애 영향을 줄일 수 있습니다.

Markdown 지식 그래프 처리 아키텍처 Markdown 입력을 검증한 뒤 AST 파서와 규칙 추출기를 거쳐 문서, 노드, 관계, 근거를 저장합니다. 별칭 통합과 검색 인덱스가 읽기 모델을 만들고, 범위별 snapshot이 정적 공개 데모와 내부 그래프 화면에 전달됩니다. MarkdownAST ParserRule ExtractorD1 GraphEvidenceFTS · AliasSnapshotSHA · profileheading · linknode · relationatomic applycommit · linesearch · mergescope · budget

설명: 파일 하나의 새 처리 결과가 끝까지 완성됐을 때만 이전 결과를 교체합니다. 사용자가 검색할 때는 저장 구조 전체를 내보내지 않고, 검색 조건과 화면 한도에 맞춘 읽기용 JSON을 반환합니다.

02 · WRITE & READ

데이터 흐름

문서 갱신과 사용자 검색을 같은 요청에서 처리하지 않습니다. 새 문서 처리가 늦거나 실패해도 사용자는 마지막으로 정상 저장된 그래프를 계속 볼 수 있습니다.

  1. 입력 검증확장자·크기·SHA-256과 parser profile을 확정하고 같은 문서의 중복 적용을 차단합니다.
  2. 구조 추출제목 계층, 링크, 인라인 코드와 명시 패턴에서 후보 노드·관계·source block을 만듭니다.
  3. 문서 단위 원자 적용새 결과가 완성되기 전까지 이전 정상 그래프를 유지하고, 적용 성공 시 문서 경계를 한 번에 교체합니다.
  4. 검색·별칭 읽기 모델표기 변형을 canonical entity로 통합하고 FTS 결과를 문서 근거와 연결합니다.
  5. 화면용 결과 생성전체 자료, 문서 한 개, 선택한 노드처럼 조회 범위에 맞춰 노드와 연결선 수를 제한합니다.
  6. 정적 공개 화면로그인 없는 공개 데모에는 읽기 전용 JSON을 배포하고 운영 DB·API·OAuth 토큰을 포함하지 않습니다.
03 · SCALE & FAILURE

확장·장애

노드 수보다 더 빠르게 관계 후보가 증가하므로 저장 용량, 검색 지연, 화면 투영 한도를 하나의 숫자로 다루면 안 됩니다. 각 단계에 별도 예산과 마지막 정상 결과가 필요합니다.

Parser profile 드리프트

문서 유형에 맞지 않는 규칙이 노드 폭증을 만들 수 있습니다. profile 버전과 추출 영수증을 함께 저장하고 표본 회귀를 수행합니다.

부분 적용

노드는 갱신됐지만 관계가 실패하면 유령 엔티티가 남습니다. 문서 경계 stage와 원자 교체로 이전 정상 상태를 보존합니다.

관계 폭발

모든 mention을 모든 엔티티와 연결하면 저장·화면 모두 악화됩니다. 관계 유형, hop, 중심성, 화면 예산을 각각 제한합니다.

검색 인덱스 지연

그래프 저장 이후 FTS가 늦게 반영될 수 있습니다. 저장 성공과 검색 가능 상태를 분리 관측하고 재색인 작업을 멱등 처리합니다.

공개 데이터와 화면 버전 불일치

데이터와 화면의 배포 시점이 다르면 링크가 깨질 수 있습니다. JSON 형식 버전과 파일 해시를 함께 확인한 뒤 같은 배포에 포함합니다.

GPU·모바일 한계

WebGL 성능이 낮은 기기에서는 노드 수·후광·자동 회전을 낮추고, 정적 목록과 검색 결과를 동일 정보의 대체 경로로 제공합니다.

04 · OPERATIONS

보안·비용

문서 파서는 입력 안의 명령을 실행하지 않고 텍스트로 취급해야 하며, 공개 그래프는 운영 인증·원문·토큰과 분리되어야 합니다. 비용은 저장량보다 재처리와 화면 밀도에서 먼저 튈 수 있습니다.

설계 축권장 경계대안과 비용
불신 MarkdownHTML·스크립트·명령형 문구를 실행하지 않고 AST 데이터로만 파싱완전한 렌더링 호환성보다 안전한 추출 규칙을 우선
인증 정보OAuth와 저장소 토큰은 서버 런타임에만 두고 브라우저 payload에서 제거클라이언트 직접 호출보다 운영 구성은 늘지만 노출면은 줄어듦
그래프 저장문서·근거·관계를 원자 적용하고 재인덱싱 작업을 멱등화단순 append보다 쓰기 비용이 들지만 정정과 롤백이 가능
화면 표시전체 저장량과 별도로 노드·연결선·탐색 단계의 상한을 적용완전한 그래프를 한 번에 그리지 않지만 모바일 안정성이 높아짐
공개 데모운영 DB 대신 읽기 전용 정적 JSON을 배포실시간 최신성은 낮지만 API·DB·OAuth 비용과 장애를 제거
관측파싱, 저장, FTS, 화면 데이터 생성, 렌더의 지연·실패를 따로 측정지표 수는 늘지만 어느 단계에서 멈췄는지 빠르게 찾을 수 있음

구현과 권리 안내: 이 페이지는 운영자가 구축한 프로젝트의 처리 흐름을 학습용으로 다시 설명합니다. 화면에서 확인할 수 있는 동작, 운영자 설명, 별도의 설계 제안은 서로 구분해 표시했습니다. 사이트 콘텐츠와 자산의 이용 조건은 이용약관에서 확인할 수 있고, 추가 확인은 운영자 이메일로 접수합니다.