wikidocs

영감 (Inspiration)

"작가는 글에만 집중하고, 출판과 배포는 기술이 해결한다."

위키독스는 오랫동안 수많은 개발자와 지식 공유자들이 책을 쓰고 나누는 공간이었습니다. 하지만 아무리 좋은 웹 에디터를 제공하더라도, 개발자들에게 가장 편안한 집필 환경은 결국 자신의 로컬 에디터(VS Code, Obsidian 등)와 Markdown, 그리고 GitHub였습니다.

로컬에서 마크다운으로 글을 쓰고 깃허브에 푸시하면, 아무런 추가 작업 없이 위키독스에 실시간으로 반영되는 완벽한 동기화 환경을 만들고 싶었습니다. 여기에 독자가 책의 방대한 내용을 더욱 쉽게 탐색할 수 있도록 돕는 AI 기반 문서 검색(RAG)을 더해, 위키독스를 단순한 '뷰어'가 아닌 '상호작용하는 기술 지식 플랫폼'으로 진화시키고자 이번 개발을 시작했습니다.

주요 기능 (What it does)

• GitHub 레포지토리 단방향 동기화: 깃허브 저장소와 위키독스의 책을 연동하여, git push 한 번으로 마크다운 문서가 실시간 파싱되어 책으로 자동 업데이트됩니다.
• AI 기반 책 검색 엔진 (RAG): LLM과 벡터 데이터베이스를 결합하여, 독자가 책 내용에 대해 질문하면 단순 키워드 매칭이 아닌 책의 전체 맥락을 분석해 정확한 코드와 답변을 제공합니다.
• 유연한 B2B SaaS 아키텍처: 기업 고객이 사내 기술 문서나 비공개 가이드를 위키독스 환경에서 독립적으로 운영할 수 있도록 커스텀 가능한 SaaS 기반을 구축했습니다.
• 구독 기반 멤버십 레이어: 독자들에게 광고 없는 독서 환경, e-Book 다운로드 혜택, 무제한 AI 검색을 제공하는 세분화된 권한 체계의 구독 모델을 지원합니다.

개발 과정 (How we built it)

기존의 견고한 레거시를 유지하면서 새로운 고성능 기능을 얹기 위해 하이브리드 아키텍처와 최신 툴체인을 도입했습니다.

• Django & FastAPI 하이브리드 백엔드: 기존의 안정적인 비즈니스 로직과 데이터베이스 관리(PostgreSQL)는 Django가 처리하고, 대규모 마크다운 동기화나 AI API 호출처럼 비동기 처리가 중요한 영역은 FastAPI로 분리하여 효율성을 극대화했습니다.
• Svelte 중심의 가벼운 프론트엔드: 사용자가 빠르게 인터랙션할 수 있도록 가볍고 직관적인 Svelte로 프론트엔드를 구성했습니다.
• uv 기반의 패키지 및 태스크 관리: 빌드 및 프로덕션 서버 환경 전체에 차세대 패키지 매니저인 uv를 전격 도입하여, 배포 스크립트와 크론탭(Crontab)의 의존성 실행 환경을 극적으로 단순화하고 속도를 개선했습니다.
• Docker & Nginx & Cloudflare 인프라: 인프라 자원을 효율적으로 쓰기 위해 Docker (Alpine 기반)로 컨테이너화하고, Nginx의 레이트 리밋(Rate Limiting) 설정과 Cloudflare 캐싱 설정을 통해 트래픽 급증에 유연하게 대응하도록 구축했습니다.

겪었던 난관들 (Challenges we ran into)

• 다양한 마크다운 문법 및 상대 경로 파싱: 옵시디언(Obsidian) 등 개별 에디터에서 사용하는 상대 경로 이미지나 위키독스 자체 문법 간의 호환성을 맞추는 작업이 까다로웠습니다. 이미지 경로가 깨지지 않으면서 안전하게 정적 자산으로 동기화되도록 예외 처리 파이프라인을 꼼꼼하게 설계해야 했습니다.
• 비동기 동기화 큐 설계: 여러 저장소에서 동시에 깃허브 웹훅(Webhook) 보낸 요청이 들어왔을 때, 서버에 병목이 생기지 않도록 백그라운드 태스크로 안전하게 이벤트를 분산·처리하는 흐름을 잡는 데 공을 들였습니다.
• RAG 검색 성능과 비용 최적화: 책의 모든 텍스트를 적절한 단위(Chunk)로 쪼개어 임베딩하고 검색 결과에 맞게 프롬프트를 구성하는 과정에서 성능 저하와 API 호출 비용 문제를 겪었습니다. 이를 해결하기 위해 청킹 전략을 정교화하고 효율적인 캐싱 레이어를 추가했습니다.

뿌듯했던 성과 (Accomplishments that we're proud of)

• 개발자 친화적인 워크플로우 완성: 로컬 환경에서 마크다운으로 책을 편집하고 깃허브에 push하는 것만으로 출판이 완료되는, 개발자에게 완벽하게 최적화된 DX(Developer Experience)를 구현했습니다.
• SaaS 전환의 신호탄: 단순 플랫폼 서비스에 머무르지 않고, 첫 기업 고객(B2B)을 성공적으로 유치하며 커스터마이징이 가능한 SaaS 모델로서의 기술적 실현 가능성을 입증했습니다.
• 패키지 관리 체계 현대화: 기존의 무거웠던 의존성 관리 도구를 uv로 완전히 전환하면서 패키지 설치 속도 향상은 물론, 서버 운영 관리 비용을 크게 낮췄습니다.

배운 점 (What we learned)

• 사용자의 워크플로우를 존중하는 설계: 최고의 플랫폼은 사용자가 기존에 쓰던 도구(Git, 마크다운 에디터)를 포기하게 만드는 것이 아니라, 그 도구를 플랫폼 안으로 자연스럽게 품어주는 것임을 다시 한번 확인했습니다.
• 인프라 아키텍처의 단순화가 주는 힘: 화려한 기술을 덧붙이는 것보다 uv run을 활용한 배포 스크립트 단일화나 Nginx 튜닝처럼 '기본적이면서 강력한' 최적화가 서비스의 장기적인 안정성을 유지하는 데 훨씬 결정적인 역할을 한다는 점을 배웠습니다.

위키독스의 향후 계획 (What's next for wikidocs)

• B2B SaaS 템플릿 표준화: 첫 고객사의 커스텀 피드백을 반영하여, 향후 다른 기업들도 클릭 몇 번으로 자사만의 독자적인 기술 문서/위키 시스템을 구축할 수 있도록 SaaS 템플릿 기능을 표준화할 예정입니다.
• 구독 및 광고 제거 멤버십 론칭: 독자와 저자 모두에게 윈-윈이 될 수 있는 유료 구독 모델을 안정적으로 정착시켜, 지속 가능한 지식 창작 생태계를 확립해 나갈 것입니다.
• 에디터 통합 에코시스템 구축: VS Code 익스텐션이나 Obsidian 플러그인을 개발·배포하여, 사용자가 위키독스 웹 브라우저를 켜지 않고도 로컬 환경에서 모든 집필 및 관리 작업을 완결할 수 있도록 생태계를 넓혀갈 계획입니다.

Built With

• django
• python