Architecture

아키텍처 개요

SSOT: docs/01-architecture.md · 스택 결정 docs/07 ADR-0001

올 러스트 워크스페이스 — 외부 crate 최소(추가는 원장 기록), 크레이트 경계는 단방향.

크레이트 구성

크레이트	역할
nbeep-core	도메인 + 포트(허브 — 다른 nbeep 크레이트 의존 0). PeerTable·TrustStore·i18n·이름 무해화
nbeep-net	전송·발견 — UDP 멀티캐스트/브로드캐스트 발견(S1~S3) + TCP 세션(LocalDirect) · 주소 후보 목록(R-21)
nbeep-crypto	Noise_XX 세션 · 신원 키(생성·영속) · SAS 지문
nbeep-safe	수신 무해화 — 위험 판정·.beepq 봉인·격리 저장·실체화
nbeep-store	영속 — 신뢰 핀 세그먼트(암호화 · 키 계층 래핑) · (예정) 암호화 대화 기록
nbeep-gfx	CPU 래스터라이저 · 텍스트 스택(글리프 폴백·광학 크기 보정)
nbeep-ctl	컨트롤 라이브러리(08-14 분리) — 컨트롤 19종 + 위젯·이벤트·그리기·테마·편집·아바타. 앱 도메인 의존 0(문자열·배율 같은 정책은 주입)
nbeep-ui	앱 화면·모달(목록·대화·프로필·설정·갤러리) — nbeep-ctl 위에 얹힌다
nbeep-plat	플랫폼 경계 — 창·IME·클립보드·시각·호스트명·MotW/quarantine 표식·종료 신호
nbeep-imgdec	(bin) 이미지 격리 디코드 — 별도 프로세스(파서 취약점 격리)
nexa-conf	설정 직렬화·영속(재사용 크레이트 — nbeep 의존 0 · ADR-0011)
nexa-beep	(bin) 진입·조립·생명주기 — 어댑터를 포트에 꽂는 유일한 지점

관통 원리 — "봉투만 본다"

릴레이는 목적지만 · 발견 패킷은 존재만 · 격리물은 메타만 · 저장 세그먼트는 헤더만 · 계측은 횟수만. 새 기능 설계의 첫 질문 = "이 계층의 봉투는 무엇인가?"

데이터 흐름 (한 판)

발견(UDP 47100 · 서명 없는 힌트)  →  목록(PeerTable — 병합 근거는 오직 PeerId)
   → 클릭 → TCP 연결(주소 후보 순차 · 워커 스레드) → Noise_XX 핸드셰이크(신원 확정)
   → TOFU 판정(메인 스레드 단일 지점 · 핀은 암호화 영속) → 다중화 세션
   → Chat(대화) | File(무해화 게이트) | Control(프로필·수신확인)

포트는 2종뿐이다 — 발견은 고정 UDP 47100(잠정 · 멀티캐스트 239.255.77.77 / ff02::beb + 브로드캐스트), 세션은 임의 TCP 포트(0.0.0.0:0 바인딩 후 그 번호를 발견 패킷에 실어 광고). 파일은 별도 포트도 별도 세션도 쓰지 않고 같은 암호 세션의 File 스트림을 탄다 — 분리되는 것은 논리 스트림과 스케줄링이지 보안 경계가 아니다.

핵심 결정 요약

• 신원 = 기기 키 지문(PeerId = X25519 공개키). 이름·IP는 신원이 아니다.
• 전송 2모드 전제(로컬 직접 v1 · 릴레이 v2 — 인터페이스는 1일차부터 2모드).
• 외부 기술은 이음새(포트) 뒤에(DR-21) — 외부 crate 타입이 포트 시그니처에 나오면 위반.
• T0(무권한)이 완전한 제품 — 관리자 권한·드라이버 불요.