[1/7] Digital Garden의 구조 설계
이 글은 실제 Abulafium 구축 이력(2026-10-09 기준)을 바탕으로 다시 작성한 공개용 실습 매뉴얼입니다.
[실제 검증]은 구축 과정에서 성공을 확인한 상태,[재현 절차]는 이를 일반화한 실행 순서,[확인 필요]는 실제 소스·대시보드를 추가 확인해야 하는 사항입니다. 명령어의<USER>,<REPO_URL>등은 자신의 환경으로 변경하세요.
이 편의 완성 목표
구축에 앞서 원본 문서의 위치, 지식 생산·동기화·출판의 경계, AI 쓰기 권한을 확정한다. 여기서는 서비스를 설치하지 않는다. 다음 편부터 이 설계도에 따라 구현한다.
1. 실제로 해결하려 했던 문제
- 과목·챕터별 Markdown 강의노트를 관리하면서 웹에서는 학생에게 필요한 콘텐츠만 제공한다.
- Obsidian에서 작성 중인 문서를 원격 Hermes Agent도 읽는다.
- Hermes가 조사·요약 결과를 Markdown으로 생성하면 다시 개인 PC의 Obsidian에 나타난다.
- GitHub는 복원 가능한 변경 이력과 공개 사이트 빌드의 기준으로 유지한다.
처음에는 GitHub Push → 농장 PC Pull만으로 충분하다고 판단했다. 이 방식은 문서를 저장하고 Push한 뒤에만 Hermes가 최신 파일을 볼 수 있고, Hermes가 만든 파일을 개인 PC로 되돌리는 흐름도 자동 해결하지 못했다. GitHub Webhook, 주기적 Pull, n8n까지 검토했지만 요구사항을 다시 정리한 후 문서 실시간 복제는 Syncthing, 버전·출판은 Git으로 분리했다. 이것이 가장 중요한 설계 변경이다.
2. 최종 구조 [실제 검증된 연결]
[개인 PC / Windows 노트북]
C:\works\abulafium\
├── garden/ ← Obsidian Vault
├── abulafium-site/ ← Docusaurus 소스
└── .git/ ← 저장소 전체의 Git 기록
│
├── garden/만 Syncthing 양방향 복제 ──────────┐
│ │
└── 검토 후 Commit · Push │
│ ▼
▼ [농장 PC: Windows + WSL2 + Docker]
[비공개 GitHub 저장소] C:\works\abulafium\garden
│ ├── Syncthing 컨테이너
▼ └── Hermes 컨테이너
[Cloudflare Workers Builds] ├── 전체 Garden 읽기
│ └── inbox/ 새 파일 쓰기
▼
[Docusaurus 공개 웹사이트]
중요한 구분: Syncthing이 garden/을 동기화해도 .git/ 기록은 전송되지 않는다. Git Push는 계속 수동으로 검토하며 실행한다. AI가 inbox/에 새 파일을 썼다고 자동 공개되는 것도 아니다.
3. 구성 요소와 책임
| 구성 요소 | 해야 하는 일 | 하지 않아야 하는 일 |
|---|---|---|
| Obsidian | Markdown 작성, 링크·첨부 관리, Hermes 화면 열기 | 웹 게시 권한의 최종 판정 |
| Syncthing | garden/ 파일의 양방향 복제 | Git 히스토리 복제 또는 버전 승인 |
| GitHub | abulafium/ 전체 버전 기록 | 미Commit 문서의 실시간 전달 |
| Docusaurus | 선택된 Markdown을 웹 페이지로 변환 | 모든 개인 문서를 무조건 공개 |
| Cloudflare Workers | 빌드·배포 및 사이트 제공 | Obsidian 편집 데이터 저장소 역할 |
| Hermes | 읽기·분석·결과물 신규 생성 | 사용자 승인 없이 기존 원고 변경·삭제 |
4. 디렉터리 설계 [구성 확인]
abulafium/
├── .git/ # Syncthing 대상 아님
├── .gitignore
├── garden/ # Obsidian과 AI가 공유하는 원본
│ ├── blog/{insights,tech-notes,life-log}/
│ ├── courses/
│ ├── projects/
│ ├── lectures/{mcp,metaverse,second-brain}/
│ ├── inbox/ # 현재 Hermes에 쓰기 허용된 위치
│ ├── ideas/
│ ├── memos/
│ ├── knowledge/
│ └── research/
├── abulafium-site/ # Docusaurus 3 + Worker 소스
└── agents/
garden/의 실제 콘텐츠 디렉터리는 Git과 Syncthing 모두 관리할 수 있지만 .git/은 공유 범위 밖에 두어야 한다. .obsidian/은 Git에서 제외하고 Syncthing에서는 대부분 공유하되 작업 공간 배치 파일만 제외하기로 했다.
5. 쓰기 권한을 최소화한 이유
처음에는 Hermes가 garden/ 전체를 읽게 했다. 이후 AI가 자료를 생성하는 실험을 위해 전체 Garden은 읽기 전용, inbox/만 읽기·쓰기로 변경했다. 이 제한은 실제 Docker 마운트로 구현하고 문서 생성까지 검증했다. 메일 요약을 memos/, 조사 결과를 research/에 자동 분류하는 것은 목표일 뿐 아직 해당 폴더의 쓰기 권한을 부여하거나 자동화하지 않았다.
6. 공개와 개인정보 경계
garden/ideas/, memos/, inbox/ 등은 개인 정보·미완성 문서가 들어갈 수 있다. GitHub 저장소가 Private이어도 공개 Docusaurus 빌드에 파일을 포함시키면 외부에 노출된다. 따라서 게시 여부는 Docusaurus의 실제 콘텐츠 수집 코드와 Worker 라우팅에서 검증해야 한다. 강의별 비밀번호 정책은 초기 기획에서 논의했지만 실제 구현 여부는 확인되지 않았다.
7. 완성 체크리스트
- 문서 원본은
garden/이라는 원칙 확정 - Git 저장소 루트는
abulafium/, Syncthing 범위는garden/만 지정 - 공개/비공개 콘텐츠 경계 정의
- AI 자동 작성은 초기에는
inbox/신규 파일로 제한 - Git Push 담당 장치와 충돌 대응 정책을 운영 전에 결정
실제 시행착오: 설계를 중간에 바꾼 이유
| 초기 구상 | 문제 | 채택한 방향 |
|---|---|---|
| Push 후 주기적 Pull | 작성 중인 문서는 Hermes가 볼 수 없음 | Syncthing 실시간 복제 |
| GitHub Webhook | 외부 HTTPS 수신 엔드포인트·인증·관리 필요 | 별도 수신 서버를 만들지 않음 |
| n8n 자동화 | 기존 수업 시연 환경까지 운영 의존성 증가 | 문서 동기화에 n8n 사용 안 함 |
| Hermes에 Garden 전체 쓰기 | 원고 덮어쓰기 위험 | inbox/만 쓰기 |