본문으로 건너뛰기

아키텍처

Maekon은 **Hexagonal Architecture (Ports & Adapters)**를 따릅니다. 코어(maekon-core)가 모든 trait 와 도메인 모델을 정의하고, 다른 모든 crate 는 그 port 들을 구현하는 어댑터(adapter) 입니다.

워크스페이스 구조​

clients/maekon-client/
├── src-tauri/              # Tauri v2 메인 바이너리 (패키지: maekon-app)
└── crates/
    ├── maekon-core         # 95개 port trait + 34개 도메인 모델 + error code
    ├── maekon-network      # JWT 인증, HTTP/SSE, gRPC, 배치 업로드
    ├── maekon-storage      # SQLite (WAL) + 31개 마이그레이션 버전
    ├── maekon-monitor      # 시스템 메트릭, 활성 윈도우, idle 감지
    ├── maekon-vision       # 화면 캡처, 델타 인코딩, OCR, PII 필터
    ├── maekon-suggestion   # SSE/gRPC 수신, 우선순위 큐, 피드백
    ├── maekon-automation   # 정책 기반 명령 실행 + 감사 로그
    ├── maekon-analysis     # LLM 세그먼트 요약, 벡터 RAG
    ├── maekon-embedding    # INT8 양자화, 유사도 검색
    ├── maekon-audio        # cpal 캡처 + Whisper STT
    ├── maekon-web          # 로컬 Axum 대시보드 + React 프론트엔드
    ├── maekon-api-contracts # 공용 API 타입
    ├── maekon-sandbox-worker # 외부 프로세스 액션 실행기
    └── maekon-lint         # 워크스페이스 린트 도구 (스탠드얼론)

의존성 규칙​

maekon-core  ←  모든 어댑터 (단방향)

어댑터는 서로를 의존하지 않습니다. 모든 crate 간 통신은 maekon-core 에 정의된 trait 를 통해서만 이뤄집니다. 이것이 핵심 불변(invariant) 입니다 — ADR-001 §1 참조.

핵심 불변 조건​

  • 모든 port trait 는 &self 사용 (&mut self 아님). 가변 상태가 필요한 구현체는 내부 가변성(Mutex, RwLock, parking_lot)으로 해결합니다.
  • 모든 port 에 #[async_trait] — Arc<dyn Trait> DI 를 위해 필수입니다.
  • 수동 mock 구현 — #[cfg(test)] mod tests 안에 작성하며, mockall 은 사용하지 않습니다.
  • 에러 전략: 라이브러리는 thiserror, 바이너리는 anyhow. 모든 외부 에러는 #[from] 으로 wrap.
  • 모든 CoreError variant 에 error code 필드 (ADR-019) — wire-format 계약이 41개 코드로 고정되어 있습니다.

이미지 처리 파이프라인​

화면 프레임은 4단계 importance 분기(maekon-vision::EdgeFrameProcessor)를 거칩니다.

Importance파이프라인
≥ 0.8풀 프레임 + OCR
≥ 0.5델타 인코딩
≥ 0.3썸네일
< 0.3메타데이터만

이미지가 기기를 떠나기 전에 PII 필터가 먼저 적용됩니다 — 전화번호, API 키, IP, 이메일, 신용카드, SSN, 파일 경로 등에 4단계 cascade(Off / Basic / Standard / Strict) 마스킹이 적용됩니다.

아키텍처 결정 기록 (ADR)​

전체 ADR 시리즈가 본 사이트에 그대로 import 되어 있습니다. 각 ADR 은 Rust 컴파일러가 강제할 수 없는 단일 설계 결정을 그 배경, 검토된 대안, 결과와 함께 기록합니다.

ADR제목
ADR-001Rust Client 아키텍처 패턴
ADR-002OS GUI 상호작용 경계와 런타임 분할
ADR-003대형 소스 파일을 위한 디렉토리 모듈 패턴
ADR-004Tauri v2 마이그레이션
ADR-005Tauri v2 거버넌스 (영문)
ADR-006Tauri IPC 커맨드 계약 (영문)
ADR-007비동기 런타임 안전 패턴 (영문)
ADR-008네트워크 회복 탄력성 패턴 (영문)
ADR-009클라이언트 아키텍처 베이스라인 (영문)
ADR-010로컬 통합 하니스 경계 (영문)
ADR-011독립 분석 파이프라인 (영문)
ADR-012적응형 계층 메모리 (영문)
ADR-013LLM 세그먼트 요약 + 벡터 RAG (영문)
ADR-014Tauri Managed State 경계
ADR-015프레임 저장소 포트 추상화
ADR-016Config Change Bus
ADR-017FeedbackSignalSink
ADR-018RegimeManager 영속성
ADR-019에러 코드 인프라

같은 파일들이 소스 저장소의 docs/architecture/ 에도 있습니다 — 본 문서 사이트는 link rewrite 가 적용된 렌더링 본입니다. ADR-005 ~ ADR-013 은 한국어 번역본이 아직 없으며 영문 본문이 그대로 표시됩니다.

다음 단계​