# 아키텍처 설계

## 핵심 철학

HaBraid는 memory backend 자체가 아니라 **기억 시각화 계층**이다.

- source of truth: MemPalace / mem0 / future memory backends
- expression layer: HaBraid wiki
- consumer: 사람 + AI

즉 HaBraid는 장기 기억을 사람이 읽기 좋고 AI가 다시 활용하기 좋은 위키 표현층으로 재구성한다.

## 데이터 흐름

```text
memory backend (MemPalace / mem0 / future backends)
        │
        ▼ read-only / adapters
    ┌──────────┐
    │  ingest   │ source → raw/ + DB items
    └────┬─────┘
         │
         ▼
    ┌──────────┐
    │  wiki     │ items/raw → wiki/ (host-following LLM)
    └────┬─────┘
         │
         ▼
    ┌──────────┐
    │  sync     │ index/log/state + optional git sync
    └──────────┘
```

## LLM 실행 계층

```text
prompt builder
   ↓
LLM gateway
   ├─ host mode (default)
   │    └─ host가 실제 모델/정책 선택
   └─ standalone / fallback
        └─ openai | zai | ollama 직접 호출
```

원칙:
- HaBraid는 모델 선택보다 **prompt orchestration**에 집중한다.
- 가능하면 host가 실제 inference를 담당한다.
- host unavailable이면 configured fallback을 사용한다.

## 모듈 의존성

```text
cli/commands.ts
    ├── sync/pipeline.ts
    │     ├── sync/git.ts
    │     ├── mempalace/ingest.ts
    │     │     └── mempalace/reader.ts
    │     └── wiki/generator.ts
    │           ├── wiki/llm.ts
    │           └── wiki/prompts.ts
    ├── vault/init.ts
    ├── vault/render.ts
    ├── vault/index.ts
    └── config.ts → types.ts
```

## 에러 처리

모든 모듈은 `WikiEngineError` 기반 커스텀 에러 사용.

대표 코드:
- `VAULT_INIT_FAILED`
- `DB_READ_FAILED`
- `LLM_CALL_FAILED`
- `GIT_SYNC_FAILED`
- `LINT_FAILED`
- `CONFIG_LOAD_FAILED`

## 동시성

- ingest: 순차 처리
- wiki generation: 순차 처리 (배치 단위)
- git sync: 순차 처리

## 현재 알려진 분리 이슈

- direct MemPalace ingest는 아직 Chroma schema mismatch 문제가 남아 있다.
- host-following LLM 전환은 이 ingest 버그와 별도 change set으로 유지한다.