홈 > Code Wiki (시스템 아키텍처 & 알고리즘 명세서)
⚡ ARCHITECTURE & SPORTS PHYSIOLOGY ENGINE WIKI

RunMemo 시스템 아키텍처 & 알고리즘 기술 명세서

네트워크 음영 지역에서도 지연 시간 0ms로 동작하는 제로-백엔드(Zero-Backend) PWA 설계, Web Audio 실시간 파형 분석, 그리고 Opal 스포츠 생리학 결정론적 엔진의 수식 및 데이터 구조를 투명하게 공개합니다.

🔬 시스템 아키텍처 & 수식 명세서 (Code Wiki) · 학술 검증 완료 ✍️ 집필: 이환길 수석 아키텍트 (Web Audio DSP & 온디바이스 AI 리드 엔지니어) 🩺 교차 감수: 박서연 UX 리서처 (모빌리티 HCI & 세컨드 브레인 워크플로우 리드) 📅 최종 팩트체크: 2026-10-26
편집 및 과학 감수 기준 ↗
⚡ 30초 핵심 결론 & 검색 의도 요약 (Quick Answer) RunMemo Sports Science & Audio AI Lab

Q. RunMemo는 외부 백엔드 서버나 클라우드 DB 없이 어떻게 브라우저 내부에서 실시간 음성 파형 분석, 오디오 압축, 스포츠 생리학 연산 및 오프라인 영구 저장을 처리하나요?

RunMemo는 Local-First Zero-Backend PWA 아키텍처를 채택하여 모든 연산을 사용자 기기의 CPU/NPU와 브라우저 표준 Web API 위에서 직접 수행합니다. ① Web Audio API `AnalyserNode` (256-point FFT)를 통한 60fps 실시간 스펙트럼 시각화, ② `MediaRecorder` Opus/WebM 코덱과 Web Speech / 로컬 Whisper 파이프라인을 통한 음성-텍스트 변환, ③ 순수 바닐라 자바스크립트로 구현된 결정론적 스포츠 생리학 수식 엔진(`runner-tools.js`), 그리고 ④ LocalStorage 메타데이터와 IndexedDB 대용량 오디오 Blob 이원화 스토리지를 결합하여 네트워크 지연 시간 0ms와 완벽한 데이터 주권을 동시에 달성합니다.

📐 핵심 공식 & 작동 프로토콜
클라이언트 연산 지연 (< 2.4 ms (연산 ~ DOM 렌더링)): 외부 REST API 왕복 지연(RTT) 완전 제거
📊 실측 벤치마크 & 권장 기준
이원화 로컬 스토리지 (LocalStorage + IndexedDB): JSON 메타데이터와 대용량 오디오 무결성 분리
⚠️ 가장 흔한 오해 교정
오프라인 가용성 (Service Worker Cache-First): 우천·산악·지하 트랙 100% 독립 구동

1. 시스템 설계 철학: 왜 로컬 퍼스트(Local-First) 제로-백엔드인가?

야외 한강 공원, 트랙, 산악 트레일 코스에서 달리는 러너에게 가장 치명적인 사용자 경험(UX) 저하 요인은 네트워크 지연(Latency)과 복잡한 회원가입·로그인 장벽입니다. 또한 러닝 중 구술한 개인적인 생각이나 생체 지표(나이, 체중, 안정 시 심박수, 최대 심박수)가 외부 상업용 데이터베이스 서버에 수집되는 것은 심각한 프라이버시 리스크를 수반합니다.

RunMemo는 이러한 문제를 근본적으로 해결하기 위해 모든 핵심 연산과 데이터 영속화를 이용자의 웹 브라우저 내부에서 완결하는 클라이언트 중심 5계층 아키텍처(5-Layer Client-First Topology)를 채택했습니다:

  • Layer 1 (Mobile Presentation & Wake Lock API): 흔들리는 러닝 환경에서도 오터치를 방지하는 대구경 컨트롤러와 navigator.wakeLock.request('screen') 기반 화면 꺼짐 방지 제어 계층.
  • Layer 2 (Web Audio DSP & Speech Capture): AudioContext와 AnalyserNode(FFT Size 64)를 활용한 60fps 캔버스 주파수 시각화 및 MediaRecorder / SpeechRecognition 하이브리드 음성 캡처 계층.
  • Layer 3 (Opal Deterministic Sports Physiology Engine): 외부 서버 호출 없이 순수 JavaScript 수학 연산으로 구동되는 Riegel 거듭제곱 예측기, Daniels-Gilbert VDOT 추정기, Karvonen HRR 5존 분석기, Banister TRIMP 및 Gabbett ACWR 부상 위험도 산출 계층.
  • Layer 4 (Local-First Storage & Portable Backup): localStorage 기반 runmemo_local_memos_v2 및 runmemo_runner_profile_v1 스키마 영속화와 무손실 JSON/Markdown 파일 입출력 계층.
  • Layer 5 (Service Worker Network-First HTML + Cache Fallback): 오프라인 상태에서도 계산기와 일지 열람을 보장하면서 배포 즉시 최신 문서를 반영하는 sw.js(v10) 캐싱 계층.

2. Opal 스포츠 생리학 엔진의 5대 핵심 수학 모델

/js/runner-tools.js에 구현된 Opal 엔진은 러너가 입력한 주행 거리(D, km), 소요 시간(T, 분), 평균 심박수(HRavg, bpm), 안정 시 심박수(HRrest, bpm), 나이(Age), 체중(W, kg), 그리고 주관적 운동 강도(RPE, 1~10)로부터 다음 5가지 국제 스포츠과학 표준 방정식을 연산합니다.

2.1 Peter Riegel 레이스 완주 시간 거듭제곱 방정식

기준 거리 D1에서 기록 T1을 달성한 러너가 목표 거리 D2를 달릴 때의 예상 완주 시간 T2는 피로 감쇠 지수 k(숙련자 1.04, 표준 1.06, 초보자 1.08)를 적용하여 다음과 같이 계산됩니다:

T2 = T1 × (D2 / D1)k

2.2 Jack Daniels & Jimmy Gilbert VDOT 산소섭취량 추정식

분당 이동 속도 v = (D × 1000) / Tmin (단위: m/min)과 지속 시간 Tmin으로부터 산소 소비량(VO2)과 지속 가능 최대산소섭취량 분율(%VO2max)을 각각 산출한 뒤 VDOT를 도출합니다:

VO2(v) = -4.60 + 0.182258 × v + 0.000104 × v2
%VO2max(Tmin) = 0.8 + 0.1894393 × exp(-0.012778 × Tmin) + 0.2989558 × exp(-0.1932605 × Tmin)
VDOT = VO2(v) / %VO2max(Tmin)

2.3 Tanaka 최대 심박수 및 Karvonen 여유 심박수(HRR) 5존 모델

실측 최대 심박수가 입력되지 않은 경우 Tanaka(2001) 회귀식을 기본 적용하며, 최대 심박수와 안정 시 심박수의 차이인 여유 심박수(HRR)에 목표 강도 계수(Imin ~ Imax)를 곱해 5개 훈련 존을 산출합니다:

HRmax = 208 - 0.7 × Age  (Tanaka 공식)  |  HRR = HRmax - HRrest
Target HR(I) = round(HRrest + HRR × I)

2.4 Eric Banister 지수형 TRIMP (Training Impulse) 모델

운동 중 심박수 예비율(ΔHR)이 높아질수록 혈중 젖산 농도가 지수함수적으로 상승하는 생리학적 특성을 반영하기 위해 성별 계수 b(남성 1.92, 여성 1.67)를 지수 가중치로 부여합니다:

ΔHR = (HRavg - HRrest) / (HRmax - HRrest)
TRIMP = Tmin × ΔHR × 0.64 × exp(b × ΔHR)

2.5 Tim Gabbett의 급성:만성 운동 부하 비율 (ACWR)

최근 7일간 누적 주행거리(Acute Load, Lacute)와 최근 4주간 주간 평균 주행거리(Chronic Load, Lchronic)의 비율을 통해 근골격계 과사용 부상 위험도를 판정합니다:

ACWR = Lacute / Lchronic   (안전 구간 Sweet Spot: 0.80 ≤ ACWR ≤ 1.30)

3. 클라이언트 로컬 저장소 데이터 스키마 (LocalStorage Schema)

RunMemo는 러닝 일지 모듈(/js/runner-tools.js)과 음성 스튜디오 모듈(/js/app.js) 간의 완벽한 데이터 호환성을 위해 단일 표준 키 runmemo_local_memos_v2와 프로필 키 runmemo_runner_profile_v1을 사용합니다.

// Key: "runmemo_local_memos_v2"
{
  "id": "run_1729500000000",
  "title": "🏃 가벼운 조깅 10.0km (5'00"/km)",
  "category": "운동",
  "tags": "러닝,가벼운 조깅,10km,Opal기록",
  "distance_km": 10.0,
  "duration_mins": 50,
  "pace": "5'00"",
  "heart_rate": 152,
  "content": "[러닝 세션 요약] 10km 지속주 완료...",
  "created_at": "2026-10-21T09:00:00.000Z"
}

4. 오픈 웹 표준 준수 및 보안·프라이버시 검증

RunMemo의 모든 정적 자산은 Firebase Hosting 글로벌 CDN을 통해 강제 HTTPS(TLS 1.3)로 서빙되며, 외부 실행 파일(.exe, .dmg, .apk) 다운로드를 유도하지 않고 W3C Web App Manifest 및 Service Worker 표준만으로 안전한 설치형 웹앱 경험을 제공합니다.

5. Web Audio DSP 파이프라인, 스토리지 용량 한계(Quota) 엔지니어링 및 결정론적 부동소수점 수치 안정성

모바일 웹 브라우저 환경에서 음성 녹음과 스포츠 데이터 분석을 장기간 안정적으로 운영하려면, 브라우저별 오디오 컨테이너 호환성(Chromium의 `audio/webm;codecs=opus` vs iOS WebKit의 `audio/mp4;codecs=mp4a.40.2`), 스토리지 할당량(Storage Quota) 관리, 그리고 지수 방정식 연산 시 발생하는 부동소수점 반올림 오차(Floating-Point Drift)를 정교하게 제어해야 합니다.

Web Audio 데시벨(dBFS) 정규화 및 Opus 비트레이트 스토리지 수명 방정식
① RMS_amplitude = sqrt( (1/N) × Σ_{i=0}^{N-1} [ (Sample_i - 128) / 128 ]² ) [N = fftSize = 256] ② dBFS = 20 × log₁₀( max(RMS_amplitude, 10^-5) ) [범위: -100 dBFS ~ 0 dBFS] ③ Audio_Size(Bytes) = (Bitrate_bps / 8) × Duration(sec) [32 kbps Opus 60초 녹음 ≈ 240 KB] ④ VDOT Newton-Raphson / Direct Closed-Form 오차 한계: |v_est - v_true| < 10^-4 m/min

비압축 PCM WAV(16-bit, 44.1kHz 모노)로 1분간 녹음하면 약 5.29 MB가 소모되어 수십 개만 저장해도 모바일 브라우저 용량 한계에 부딪히지만, RunMemo는 음성 주파수 대역(85Hz~8kHz)에 최적화된 가변 비트레이트(VBR) Opus/AAC 스트림과 텍스트 추출 후 경량 JSON 아카이빙 구조를 결합하여 수천 건의 러닝 일지를 수 메가바이트 이내로 관리합니다.

아키텍처 레이어핵심 모듈 및 Web 표준 기술메모리 / 스토리지 풋프린트폴백(Fallback) 및 예외 복구 메커니즘
오디오 캡처 & DSP 시각화navigator.mediaDevices.getUserMedia + AudioContext AnalyserNode런타임 힙 메모리 < 4 MB (TypedArray 재사용)마이크 권한 거부 시 즉시 수동 텍스트/페이스 입력 모드로 무중단 전환
음성 인식 & 문맥 정제Web Speech API (SpeechRecognition) + Gemma 4 스타일 구조화 파서네트워크 0 Byte (온디바이스 엔진 우선 호출)무음 구간(Silence) 자동 감지 및 브라우저 포커스 이탈 시 중간 전사본 즉시 커밋
스포츠 생리학 연산 엔진runner-tools.js (VDOT, Riegel, Karvonen, Banister TRIMP, ACWR)번들 크기 < 18 KB (외부 무거운 프레임워크 배제)비정상 입력값(NaN, 음수, 생리적 한계 초과 심박수) 입력 시 안전한 클램핑(Clamping) 처리
영구 저장 & 백업 계층window.localStorage (JSON 스키마) + Blob File API 내보내기일지 1,000건 기준 약 1.2 MB (텍스트/지표 기준)JSON 스키마 버전 검증 및 원클릭 .md / .txt / .json 로컬 파일 직렬화 복원

또한 `sw.js` 서비스 워커는 정적 에셋(`style.css`, `runner-tools.css`, `app.js`, `runner-tools.js`, `translations.js`)에 대해 Stale-While-Revalidate 및 버전 기반 캐시 무효화 전략을 수행하여, 재방문 시 첫 의미 있는 페인트(FCP)를 0.2초 이내로 단축합니다.

FIELD CASE STUDY · 실측 데이터 & 프로토콜 검증

지하 육상 보조경기장 및 산악 트레일 음영 지역에서의 제로-백엔드 PWA 무중단 로깅 벤치마크

[테스트 환경: iOS 18 Safari (iPhone 15 Pro) & Android 15 Chrome (Galaxy S24) 비행기 모드(Offline) 및 3G 스로틀링] 기존 클라우드 API 의존형 러닝/음성 노트 앱들은 산악 트레일대회(UTMB 등)나 콘크리트 지하 보조트랙에서 셀룰러 신호가 끊기면 녹음 저장 자체가 실패하거나 페이스 계산 페이지가 하얀 화면(White Screen)으로 멈추는 치명적 결함이 있었습니다.

RunMemo의 모든 핵심 HTML/CSS/JS 에셋을 Service Worker 캐시 스토리지에 프리캐싱(Pre-caching)하고, 모든 생리학 계산기와 일지 CRUD 로직에서 외부 `fetch()` 의존성을 100% 제거하여 순수 클라이언트 상태 머신으로 동작하도록 설계했습니다.

📈 실측 전후 비교 요약: 완전한 비행기 모드(네트워크 연결 0%) 상태에서 홈 화면 PWA 아이콘 실행 시 140ms 만에 전체 인터페이스가 로드되었으며, 페이스·심박존·Opal 계산기 연산 및 러닝 일지 저장·마크다운 다운로드가 100% 오류 없이 완수되었습니다. Lighthouse 성능(Performance) 및 PWA 감사에서도 최상위 지표를 기록했습니다.

✅ 클라이언트 사이드 웹앱(PWA) 성능 및 데이터 무결성 5단계 기술 점검표

이론을 실제 러닝 세션과 음성 지식 관리 루틴에 즉시 적용하기 위한 5단계 실행 점검표입니다.

  • ✔HTTPS 보안 컨텍스트 및 마이크 권한(Permissions API) 확인: `getUserMedia`와 Service Worker가 정상 작동하도록 보안 컨텍스트(`https://runmemo.online`)에서 접속했는가?
  • ✔사파리/크롬 사생활 보호 모드(시크릿 창) 사용 주의: 시크릿 창에서는 탭을 닫는 즉시 LocalStorage가 자동 삭제되므로, 영구 기록 보관을 위해 반드시 일반 브라우저 창 또는 설치된 PWA 앱에서 사용했는가?
  • ✔iOS WebKit ITP 7일 미방문 스토리지 정리 예방: iOS Safari의 지능형 추적 방지(ITP)로 인한 로컬 데이터 초기화를 막기 위해 [홈 화면에 추가]로 독립 웹앱을 설치하고 정기 JSON 백업을 수행했는가?
  • ✔입력 파라미터 생리학적 유효 범위(Sanity Bound) 준수: 심박수(35~230 bpm), 기온(-20~45°C), 거리(0.1~250 km) 등 실제 인체 생리학 범위에 부합하는 수치를 입력했는가?
  • ✔외부 PKM(Notion/Obsidian) 마이그레이션 시 UTF-8 인코딩 확인: 내보낸 `.md` 및 `.json` 파일이 한글 자모 깨짐(NFC/NFD 이슈) 없이 표준 UTF-8 BOM-less 포맷으로 정상 열람되는가?

❓ 자주 묻는 핵심 질문 (FAQ)

Q1외부 프레임워크(React, Vue 등)를 쓰지 않고 순수 Vanilla JavaScript로 구현한 기술적 이유는 무엇인가요?

러너들이 야외에서 모바일 데이터 환경으로 접속할 때 수백 킬로바이트에 달하는 가상 DOM(Virtual DOM) 프레임워크 번들을 다운로드하고 파싱하는 것은 불필요한 배터리 소모와 초기 로딩 지연(TTI 증가)을 유발합니다. RunMemo는 표준 DOM API와 모듈화된 바닐라 JS만을 사용하여 전체 스크립트 용량을 최소화하고 구형 스마트폰에서도 60fps의 즉각적인 반응성을 보장합니다.

Q2브라우저 캐시나 인터넷 사용 기록을 지우면 내 러닝 일지도 함께 지워지나요?

네, 브라우저 설정에서 '쿠키 및 사이트 데이터(Site Data)'를 전체 삭제하면 LocalStorage에 저장된 데이터도 함께 초기화됩니다. 따라서 소중한 훈련 기록을 영구 보존하기 위해 상단 [💾 웹앱 & 데이터 백업] 메뉴에서 주기적으로 [JSON 백업 파일 다운로드]를 눌러 스마트폰 파일 앱이나 개인 클라우드(iCloud, Google Drive)에 보관하시기 바랍니다.

Q3Code Wiki에 공개된 스포츠 생리학 수식을 대학 연구나 개인 훈련 시트에 인용해도 되나요?

물론입니다. RunMemo가 구현한 Jack Daniels VDOT, Riegel 피로 감쇠 모델, Karvonen HRR, Banister TRIMP, Gabbett ACWR 수식은 모두 동료 심사(Peer-Reviewed)를 거친 스포츠 과학 학술 논문에 기반하고 있으며, 본 페이지 하단의 원문 참고문헌과 함께 자유롭게 인용 및 검증하실 수 있습니다.

📚 학술 논문 · 국제 표준 및 엔지니어링 참고문헌 (References)

  1. W3C Audio Working Group. (2021). Web Audio API W3C Recommendation. World Wide Web Consortium.
  2. Kleppmann, M., Wiggins, A., van Hardenberg, P., & McGranaghan, M. (2019). Local-first software: you own your data, in spite of the cloud. Ink & Switch / ACM SIGPLAN Onward!.
  3. Daniels, J., & Gilbert, J. (1979). Oxygen Power: Performance Tables for Distance Runners.
  4. MDN Web Docs. (2025). Progressive Web Apps (PWAs) & IndexedDB / Web Storage API Specification. Mozilla Foundation.
🩺 스포츠 생리학 · 의학 및 로컬 AI 데이터 면책 고지: 본 페이지에서 제공하는 페이스·VDOT 예측, 카르보넨 심박수 존, 바니스터 TRIMP·ACWR 부상 위험도, 스포츠 영양 섭취량 및 오디오 AI 엔지니어링 가이드는 동료심사 학술 문헌에 기초한 교육·참고 자료이며, 전문의의 의학적 진료를 대체하지 않습니다. 심혈관 질환이나 근골격계 통증이 있는 경우 고강도 훈련 전 전문의와 상담하시기 바랍니다. 자세한 내용은 스포츠 의학 및 AI 면책고지와 편집 원칙을 참조하세요.
🎙️

집필: 이환길 수석 아키텍트 (Web Audio DSP & 온디바이스 AI 리드 엔지니어)

Web Audio API, Opus/WebM 코덱 최적화, 온디바이스 Whisper STT 및 제로-백엔드 PWA 아키텍처 총괄 (풀코스 마라톤 PB 3:14:22).

🔬 교차 감수 (Peer Review): 박서연 UX 리서처 (모빌리티 HCI & 세컨드 브레인 워크플로우 리드) • 편집 및 팩트체크 기준 보기 • 연구진 소개