아키텍처 — Star Topology

🚧 설계 단계 — 아직 구현 안 됨

이 페이지는 ainote 의 향후 기능을 미리 문서화한 것입니다. 현재 @ainote/mcp v1.1.x 에는 vault / sync 도구가 포함돼 있지 않습니다. 도구 호출 시 Tool not found 에러를 받게 됩니다.

ainote sync 는 hub-and-spoke (별 모양). P2P (디바이스끼리 직접) 안 함.

그림

                     ┌────────────────────┐
                     │     ainote hub     │
                     │  api.ainote.dev    │
                     │  (PostgreSQL+Git)  │
                     └─────────┬──────────┘
                               │
        ┌──────────────┬───────┼───────┬──────────────┐
        │              │       │       │              │
        ▼              ▼       ▼       ▼              ▼
   [macmini]      [macbook]  [iOS]  [iPad]      [linux desktop]
   spoke 1        spoke 2    s.3    s.4         s.5

각 spoke 는 hub 와만 sync. spoke ↔ spoke 직접 X.

왜 P2P 가 아닌가

rclone bisync 포럼 컨센서스:

"If you are bisyncing more than two devices, set them up in a star topology — each spoke synced with the same hub consistently. Never device-to-device."

이유:

N 개 디바이스 → P2P 페어 N(N-1)/2 (3개 → 3, 5개 → 10, 10개 → 45)
모든 페어가 충돌 가능 → 디버깅 불가능
Star: N 개 → N 페어. 모든 충돌이 hub 에서 한 곳에서

hub 의 역할

┌────────────────────────────────────────────────┐
│                ainote hub                       │
├────────────────────────────────────────────────┤
│ 1. 모든 변경 (commit + HLC) 단일 진실 저장        │
│ 2. spoke 의 last_known_state 추적               │
│ 3. 충돌 감지 (5분 임계)                          │
│ 4. 모든 spoke 에 push 알림 (FCM/APNs/WebSocket)  │
│ 5. 부분 sync — manifest 기준 필터                │
│ 6. WORM audit log (변경 이력 영구)               │
└────────────────────────────────────────────────┘

spoke 의 역할

┌────────────────────────────────────────────────┐
│              spoke (디바이스)                    │
├────────────────────────────────────────────────┤
│ 1. 로컬 manifest.yml — 어떤 파일을 어디로         │
│ 2. state.json — 마지막 sync 상태                 │
│ 3. sync-now.sh — 수동 sync 트리거                │
│ 4. conflicts/ — 5분 임계 깨면 양쪽 보존           │
│ 5. log/*.jsonl — 월별 이벤트 로그 (append-only)   │
└────────────────────────────────────────────────┘

자세히: manifest.yml 작성, sync-now 알고리즘.

한 사이클

[spoke A 변경]          [hub]                [spoke B]
     │                    │                      │
     │  sync_push          │                      │
     ├───────────────────►│                      │
     │                    │  WebSocket notify    │
     │                    ├─────────────────────►│
     │                    │                      │
     │                    │      sync_pull        │
     │                    │◄─────────────────────┤
     │                    │                      │
     │                    │      변경 전송         │
     │                    ├─────────────────────►│

평균 지연: 1초 (WebSocket) ~ 30초 (cron).

페일오버

hub 다운 시:

spoke 는 로컬 작업 계속
변경은 로컬 log/jsonl 에 누적
hub 복구 시 일괄 push

hub 데이터 손실 시:

모든 spoke 의 git working tree 가 백업
spoke 1대를 새 hub 으로 promote 가능

새 디바이스 추가

1. 새 기기에 manifest.yml + device.id 생성
2. ainote sync_pull --initial
3. hub 의 모든 sync 항목 다운로드
4. state.json 초기화
5. 정상 sync 사이클 시작

자세히: 새 디바이스 셋업.

아키텍처 — Star Topology ​

그림 ​

왜 P2P 가 아닌가 ​

hub 의 역할 ​

spoke 의 역할 ​

한 사이클 ​

페일오버 ​

새 디바이스 추가 ​

다음 ​