openGym 딥다이브
— 데이터베이스도 프레임워크도 없이, 파일 몇 개로 굴러가는 자가호스팅 헬스 기록 앱

1프로젝트 한 줄 요약

openGym이 하는 일은 단순하다. 요일별 운동 계획을 짜고, 운동할 때 세트마다 무게와 횟수를 찍고, 체중을 기록하고, 그래프로 본다. Hevy·Strong·FitNotes 같은 앱이 이미 하는 일이다.

다른 점은 어디서 도는가다. 이 앱은 도커 컨테이너 세 개로 내 서버(집에 있는 라즈베리파이든 클라우드 VM이든)에서 돌고, 기록은 그 서버의 ./data 폴더 안 JSON 파일로 남는다. 회사가 망해도, 요금제가 바뀌어도, 내 폴더는 내 것이다.

그리고 여기서 기술적으로 흥미로운 선택들이 시작된다. 보통 이런 앱을 만들면 Express로 API를 짜고 PostgreSQL을 붙이지만, openGym은 둘 다 쓰지 않는다. 서버는 Node에 기본으로 들어 있는 http 모듈만 쓴 파일 하나고, 데이터베이스 자리는 JSON 파일이 대신한다. 서버가 실행 시점에 필요로 하는 외부 패키지는 단 두 개다 — 패스키 검증용과 푸시 알림용.

2왜 지금 주목받는가

① 자가호스팅 진영에 헬스 앱 칸이 비어 있었다

메모(Joplin), 사진(Immich), 미디어(Jellyfin), 가계부(Firefly III)처럼 상용 SaaS를 대체하는 자가호스팅 앱은 분야마다 대표 주자가 있다. 그런데 운동 기록은 오래 비어 있었다. 이 분야 앱은 대부분 폰 전용 상용 앱이고, 기록이 그 회사 서버에 쌓인다.

결정적인 건 이사 오는 길을 열어 뒀다는 점이다. FitNotes(안드로이드·iOS 두 포맷)·Strong·Hevy의 내보내기 파일과 애플 건강의 체중 데이터를 그대로 가져온다. 기존 앱 사용자가 기록을 버리지 않고 넘어올 수 있다.

② 의존성 개수가 비정상적으로 적다

요즘 웹 앱은 npm install 한 번에 수백 개 패키지가 딸려 온다. openGym의 실행 시점 의존성은 아래가 전부다.

api/package.json  (서버)
  "@simplewebauthn/server": "^13.1.1"   # 패스키 검증
  "web-push": "^3.6.7"                  # 푸시 알림
  → 끝. Express도 DB 드라이버도 없다.

frontend/package.json  (웹)
  react / react-dom  19.2.7
  react-router-dom   7.18.2
  zustand            5.0.14
  @capacitor/*       (모바일 앱 빌드용 4개)
  → 상태관리·라우팅·리액트. 차트도 아이콘도 자체 구현.

차트 라이브러리(Recharts 등)도, 아이콘 팩도, i18n 라이브러리도 없다. 꺾은선 그래프(LineChart.jsx), 잔디밭 히트맵(Heatmap.jsx), 근육 지도(BodyMap.jsx), 아이콘 세트(Icon.jsx), 번역 엔진(lib/i18n.js 56줄)이 전부 저장소 안에 직접 쓰여 있다.

③ 자가호스팅인데 비밀번호가 없다

개인이 띄운 서버에서 가장 흔한 사고는 비밀번호다. 재사용된 비밀번호, 유출된 해시, 무차별 대입. openGym은 비밀번호 항목 자체를 만들지 않았다. 로그인은 패스키 — 폰의 지문·얼굴 인식으로 서명하고, 서버는 공개키만 들고 있다가 서명을 검증한다.

④ "왜 이 무게인가"를 앱이 설명한다

대부분의 기록 앱은 지난 기록을 보여 주는 데서 끝난다. openGym은 다음 세션을 열면 무게가 이미 채워져 있고, 그 옆에 이유가 적혀 있다. "지난번에 전 세트를 다 채웠으니 2.5kg 올립니다", "세 번 정체됐으니 10% 내립니다" 같은 문장이다.

이게 가능한 건 진행 규칙(선형 증량, Greyskull LP, 더블 프로그레션, 시간 증가)이 UI에 흩어져 있지 않고 frontend/src/lib/progression.js의 순수 함수 한 곳에 모여 있기 때문이다. 함수가 돌려주는 값에 why 필드가 아예 들어 있다. 4절에서 코드를 직접 본다.

⑤ 그리고 원본이 사라졌다

냉정하게 보면, 이번 트렌딩에는 저장소가 없어졌다는 사실 자체도 섞여 있다. 목록에 오른 주소는 사라진 저장소를 보존하는 계정의 사본이고, 이런 항목은 "이거 왜 없어졌지?"라는 호기심으로 클릭 수를 모은다. 프로젝트의 기술적 가치와는 별개의 동력이다 — 위 ①~④가 진짜 볼거리고, ⑤는 지금 이 주에만 유효한 이유다.

3기술 스택 전체 지도

백엔드 — api/server.js 554줄이 전부다

프론트엔드 — React 19 SPA

모바일 — 같은 코드로 서버 없는 앱을 만든다

Capacitor 7로 같은 프론트엔드를 안드로이드 앱(APK)으로 감싼다. 그런데 단순 포장이 아니다. VITE_MOBILE=1로 빌드하면 동작 방식이 세 군데 갈린다.

모바일에서 굳이 파일시스템에 한 번 더 저장하는 이유는 iOS WebView가 저장 공간이 부족할 때 localStorage를 지울 수 있기 때문이다. "브라우저 저장소는 언제든 날아갈 수 있다"는 전제를 그대로 코드로 옮긴 셈이다.

인프라 — 컨테이너 3개

배포 옵션으로 render.yaml도 들어 있지만 정의된 서비스는 웹 하나뿐이다. API까지 한 번에 올라가지는 않으니, Render로 올릴 생각이면 API는 따로 배포해야 할 것으로 보인다(저장소에 설명이 없어 추정).

데이터셋 — 운동 1,324개는 어디서 오나

운동 정보는 외부 저장소 hasaneyldrm/exercises-dataset에서 온다. 다만 글과 그림을 갈라 놓았다.

• 글(이름·부위·장비·단계별 설명) — frontend/src/lib/exercises-data.js에 888KB짜리 배열로 박혀 있다. 빌드에 포함되니 네트워크 요청이 없다.
• 그림(사진 1,324장 + GIF 1,324개, 약 137MB) — 저장소에 함께 커밋돼 있고, 도커의 media 서비스가 없을 때만 받아 온다(멱등).
• 영어 외 설명 — frontend/src/instr/*.js로 언어별 분리. 필요할 때만 불러온다.

한 항목의 실제 모양은 이렇다. 키 이름을 두 글자로 줄인 게 눈에 띈다 — 888KB 파일에서는 키 이름 길이도 용량이다.

{"id":"0001","n":"3/4 sit-up","bp":"waist","eq":"body weight",
 "tg":"abs","mg":"hip flexors","sm":["hip flexors","lower back"],
 "st":["Lie flat...","..."],
 "img":"0001-2gPfomN.jpg","gif":"0001-2gPfomN.gif"}

4아키텍처 심화 분석

설계 패턴 ① — 주소를 하나로 묶은 건 취향이 아니라 패스키 때문

프론트와 API를 다른 주소(예: app.example.com / api.example.com)로 나누는 건 흔한 구성이다. openGym은 nginx 하나가 둘 다 서빙한다. nginx.conf 주석에 이유가 적혀 있다 — WebAuthn 때문이다.

location /api/ { proxy_pass http://api:3000; ... }   # /api → 백엔드
location / { try_files $uri $uri/ /index.html; }      # 나머지 → SPA

패스키는 "어느 사이트의 열쇠인가"를 RP_ID(호스트명)로 못 박는다. 프론트가 만든 인증 요청과 API가 검증하는 origin이 어긋나면 브라우저가 그냥 거부한다. 그래서 .env의 RP_ID·ORIGIN 두 값이 실제 주소와 정확히 맞아야 하고, 문서에도 "로그인 문제는 대부분 이 둘의 불일치"라고 적혀 있다.

설계 패턴 ② — 파일이 곧 데이터베이스, 다만 원자적으로

DB를 안 쓰면 가장 무서운 건 쓰는 도중에 프로세스가 죽는 것이다. 파일이 반쯤 쓰인 채 남으면 JSON이 깨지고, 그게 곧 계정 전체 소실이다. openGym은 이걸 atomicWrite로 막는다 — 임시 파일에 다 쓴 뒤 rename으로 갈아 끼운다. 같은 파일시스템 안에서 rename은 쪼개지지 않는 한 번의 동작이라, 결과는 "옛 파일" 아니면 "새 파일"뿐이고 그 중간은 없다.

대신 이 구조는 동시 접속이 많아지면 무너진다. 사용자 파일 하나를 통째로 덮어쓰기 때문에, 같은 계정을 두 기기에서 동시에 쓰면 나중 쓰기가 앞 쓰기를 지운다. 가족 몇 명이 쓰는 규모라서 성립하는 선택이지, 일반적인 정답은 아니다.

설계 패턴 ③ — 로컬 우선, 서버는 나중에 따라온다

운동 중에 지하 헬스장에서 신호가 끊기는 건 흔한 일이다. 그래서 상태 관리는 서버가 아니라 브라우저 저장소가 주인이다.

여기서 한 줄이 특히 흥미롭다. 서버로 보내기 직전에 진행 중인 운동 세션을 일부러 지운다.

delete body.state.active   // 진행 중인 운동은 서버에 저장하지 않는다

설계 패턴 ④ — 세션 쿠키를 직접 만들었다

JWT 라이브러리도 안 쓰고 서명 토큰을 직접 만든다. 페이로드는 사용자ID:만료시각:세션버전 세 조각이 전부다.

function sign(payload) {
  const mac = crypto.createHmac('sha256', SECRET).update(payload).digest('base64url');
  return payload + '.' + mac;
}

세 번째 조각인 세션 버전(sv)이 이 설계의 핵심이다. 서버는 발급한 쿠키를 저장하지 않는다(그래야 DB가 필요 없다). 그러면 "모든 기기에서 로그아웃"을 어떻게 할까? 사용자 레코드의 버전 숫자를 1 올린다. 이미 나가 있는 쿠키들은 전부 옛 버전을 달고 있으니 한꺼번에 무효가 된다. 서명 키 SECRET은 첫 실행 때 ./data/secret에 랜덤으로 생성되고 권한 0600으로 잠긴다.

설계 패턴 ⑤ — 진행 규칙을 순수 함수로 격리하고, 이유까지 돌려준다

이 저장소에서 가장 배울 게 많은 부분이다. "다음에 몇 kg를 들 것인가"는 화면 코드에 한 줄도 없다. lib/progression.js의 함수가 무게 · 종류 · 이유를 한 덩어리로 돌려준다.

if (last.ok) {
  const dbl = policy === 'greyskull' && last.goal > 0 && last.amrap >= last.goal * 2
  const step = dbl ? inc * 2 : inc
  return {
    policy, kind: 'up', weight: snap(w + step, inc),
    why: dbl
      ? ['Last set hit {0} reps — twice the target, so take a double jump of {1} {2}.',
         last.amrap, step, unit]
      : ['Every rep last time — {0} {1} more.', step, unit]
  }
}
if (stalls >= deloadAt) {
  const dw = deloadTo(w, inc)          // DELOAD_FACTOR = 0.9 → 10% 감량
  return { policy, kind: 'deload', weight: dw, why: [...] }
}

why가 문장이 아니라 배열인 게 포인트다. 첫 칸이 번역 키가 되는 틀이고 나머지가 채워 넣을 값이라, 12개 언어 어디서든 같은 이유를 자기 언어로 말할 수 있다. 로직과 문구를 섞지 않은 것이다.

설계 패턴 ⑥ — 모르는 건 대답하지 않는다 (1RM 추정)

1RM(딱 한 번 들 수 있는 최대 무게)은 실제로 재기 위험해서 공식으로 추정한다. openGym은 공식 세 개를 넣어 뒀는데, 더 눈에 띄는 건 거절 조건이다.

export const REP_CAP = 12
export const FORMULAS = {
  epley:   (w, r) => w * (1 + r / 30),      // Epley 1985
  brzycki: (w, r) => w * 36 / (37 - r),     // Brzycki 1993
  lombardi:(w, r) => w * Math.pow(r, 0.1)   // Lombardi 1989
}
export function estimate1RM(w, r, formula = 'epley') {
  ...
  if (reps > REP_CAP) return null      // 12회 초과는 추정하지 않는다
  ...
}

12회를 넘기면 공식들이 서로 크게 어긋나 숫자가 의미를 잃는다. 그래서 그럴듯한 값을 만들어 내는 대신 null을 돌려준다. 재미있는 건 테스트가 이 판단을 수치로 검증한다는 점이다 — onerm.test.js는 1회에서 세 공식이 정확히 일치하고, 2~8회에선 차이가 6 이내이며, 12회에서 그 차이가 최대가 됨을 단언한다. 테스트가 "왜 상한이 12인가"를 문서 대신 설명하고 있다.

설계 패턴 ⑦ — 맨몸 운동은 무게 대신 횟수로, 그것도 상한을 두고

푸시업에 "2.5kg 증량"은 말이 안 된다. 그래서 무게가 0이면 횟수를 올리고, 정해진 상한에 닿으면 세트를 하나 늘린다. 그런데 세트도 무한정 늘리지 않는다.

if (sets <= MAX_BW_SETS) return { kind:'up', weight:0, reps:bottom, sets, why:[...] }
return { kind:'hold', weight:0, reps:goal,
  why:['{0} sets of {1} — time to add weight or move to a harder variation.', sets-1, goal] }

MAX_BW_SETS = 6. 여섯 세트를 넘어가면 앱이 증량을 멈추고 "이제는 무게를 달거나 더 어려운 동작으로 가라"고 말한다. 세트만 늘리는 걸 발전으로 착각하지 말라는 판단을, 숫자 하나로 코드에 넣은 것이다.

설계 패턴 ⑧ — RIR과 RPE를 저장이 아니라 조회에서 변환한다

세트가 얼마나 힘들었는지 적는 척도가 두 가지다. RIR(몇 개 더 할 수 있었나)과 RPE(10점 만점 체감). 둘은 RPE = 10 − RIR로 서로 바꿀 수 있다.

export const rirOf = s =>
  !s ? null : s.rir != null ? s.rir : s.rpe != null ? 10 - s.rpe : null
export const toScale = (kind, rir) =>
  rir == null ? null : Math.round((kind === 'rpe' ? 10 - rir : rir) * 10) / 10

기록은 찍힌 그대로 두고(RPE로 적었으면 RPE로 남는다), 집계할 때만 RIR로 정규화한다. 설정을 바꿔도 과거 기록을 소급해 고치지 않는다. 다른 앱에서 RPE로 가져온 기록과 여기서 RIR로 적은 기록이 한 파일에 섞여도 아무 문제가 없는 이유다.

설계 패턴 ⑨ — 알림 검사 주기가 60초가 아니라 10초인 이유

"오늘 운동 예정인데 아직 기록이 없으면 알려 준다"는 기능을 setInterval로 돌리는데, 주기가 10초다. 주석에 이유가 적혀 있다 — 1분 주기는 정각에 맞춰 도는 게 아니라서, 목표한 분을 최대 59초까지 놓칠 수 있다. 10초로 줄이면 오차가 9초 안으로 들어온다. 각 사용자의 "지금"은 Intl.DateTimeFormat으로 그 사람의 시간대 기준으로 계산한다.

휴식 타이머 알림은 다르다. 클라이언트가 setTimeout으로 예약을 걸어 두었다가, 탭이 백그라운드로 가서 스스로 타이머를 못 돌릴 때만 서버 푸시가 대신 울린다.

설계 패턴 ⑩ — 화면 꺼짐 방지는 "의도"를 따로 기억해야 한다

세트 사이에 폰이 꺼져 잠금 화면으로 돌아가면 기록하기가 번거롭다. Wake Lock API로 화면을 켜 두는데, 문제는 브라우저가 탭 전환·화면 잠금 때마다 이 잠금을 자동으로 풀어 버린다는 점이다. 한 번 요청하고 끝내면 안 된다.

// App.jsx — 라우트가 아니라 "운동이 진행 중인가"에 묶는다
useWakeLock(!!S.active && S.keepAwake !== false)

그래서 lib/wakelock.js는 wanted라는 플래그로 사용자의 의도를 따로 들고 있다가, 화면이 다시 보일 때마다 잠금을 재요청한다. 그리고 이 조건이 화면(라우트)이 아니라 "운동 중인가"에 걸려 있어서, 기록 도중 통계 탭을 잠깐 봐도 화면이 꺼지지 않는다. iOS 저전력 모드처럼 거부당하는 상황에서는 조용히 넘어간다 — 사용자가 할 수 있는 게 없기 때문이다.

5디렉토리 구조 해부

규모 감각

읽기 순서 추천

1. api/server.js — 554줄이라 한 번에 읽힌다. 웹 서버가 실제로 무엇을 하는지가 압축돼 있다.
2. frontend/src/lib/progression.js + progression.test.js — 도메인 규칙을 순수 함수로 짜는 법.
3. frontend/src/store/useStore.js — 로컬 우선 동기화 193줄.
4. docker-compose.yml + nginx.conf — 세 컨테이너가 어떻게 한 주소로 합쳐지는지.
5. frontend/src/lib/i18n.js — 라이브러리 없이 번역을 붙이는 최소 구현.

6학습 포인트

① 프레임워크 없는 Node 서버가 실제로 어떻게 생겼나

Express를 쓰면 app.get('/x', ...)가 무슨 일을 하는지 안 보인다. openGym의 라우터는 객체 하나와 조회 한 번이다.

http.createServer(async (req, res) => {
  const url = new URL(req.url, 'http://x');
  const key = req.method + ' ' + url.pathname;
  const handler = routes[key];
  if (!handler) return json(res, 404, { error: 'not found' });
  try { await handler(req, res); }
  catch (e) { if (!res.headersSent) json(res, 500, { error: 'server error' }); }
}).listen(PORT, ...)

이 20줄을 읽고 나면 미들웨어·라우터·에러 핸들러가 프레임워크에서 무엇을 대신해 주고 있었는지가 선명해진다. 물론 값도 안다 — 경로 파라미터(/users/:id)가 없고, 요청 한도 제한도 없다. 저장소는 후자를 리버스 프록시의 몫으로 넘긴다고 명시한다.

② 패스키 로그인의 전체 흐름

등록 옵션에 residentKey: 'required'가 걸려 있다. 아이디를 먼저 입력받지 않고 "이 기기에 저장된 openGym 열쇠"를 바로 고르게 하는 설정이다. 자가호스팅 앱에서 가입 화면을 최소화하는 실용적인 선택이다.

③ 오프라인을 견디는 상태 관리

Zustand 자체는 작은 라이브러리지만, 여기서 배울 건 라이브러리 사용법이 아니라 동기화 규율이다.

• 화면은 항상 로컬 상태를 그린다. 네트워크를 기다리지 않는다.
• 변경은 localStorage에 즉시, 서버에는 1.5초 디바운스로.
• gym_dirty 플래그로 "아직 못 보낸 변경"을 표시 → 오프라인에서도 잃지 않는다.
• 합칠 수 없는 상태(진행 중 세션)는 애초에 동기화 대상에서 뺀다.
• boot()이 세 모드(일반 / 모바일 / 데모)를 한 곳에서 분기한다.

④ 라이브러리 없이 번역 붙이기

lib/i18n.js는 56줄이다. 핵심은 두 가지 — Vite의 import.meta.glob으로 언어 파일을 자동으로 모으고, React의 useSyncExternalStore로 언어 변경을 화면에 전파한다. 영어는 번들에 들어가고 나머지 11개는 고를 때 받아온다. 그리고 번역 키가 빠지는 사고를 scripts/check-locales.mjs가 막는다 — 기준을 특정 파일이 아니라 모든 언어 파일 키의 합집합으로 잡아서, 새 키를 한 언어에만 넣어도 나머지가 걸린다.

⑤ 서비스 워커를 41줄로 쓰는 법

운동 사진·GIF   → cache-first  (한 번 받으면 끝, 안 바뀜)
그 외 요청       → network-first, 실패하면 캐시
HTML 없음        → index.html 로 폴백 (SPA)
push / notificationclick 도 여기서 처리

Workbox 없이 이 정도면 충분하다는 걸 보여 준다. 캐시 전략을 자원 성격에 따라 둘로만 나눈 판단이 핵심이다.

⑥ 도커 크로스 빌드의 함정

FROM --platform=$BUILDPLATFORM node:22-alpine AS build

--platform=$BUILDPLATFORM이 빌드 스테이지에만 붙어 있다. 이유가 주석에 적혀 있는데, 라즈베리파이(arm64)용 이미지를 x86 PC에서 만들 때 QEMU 에뮬레이션 아래서 esbuild·rollup의 네이티브 바이너리가 깨지는 문제를 피하기 위해서다. 빌드 결과물은 그냥 정적 파일이라 아키텍처와 무관하니, 빌드는 내 PC 아키텍처로 하고 실행 이미지만 대상 아키텍처로 두면 된다. 멀티 아키텍처 이미지를 만들어 본 사람만 아는 종류의 함정이다.

⑦ CSV를 진짜로 파싱해야 하는 이유

다른 앱에서 기록을 가져오는 기능에 CSV 파서가 직접 구현돼 있다. 콤마로 split하지 않는 이유는 명확하다 — "Bench Press, Close Grip" 같은 운동 이름이 실제 내보내기 파일에 들어 있고, 그러면 열이 통째로 밀린다. 게다가 에러가 나지 않고 조용히 어긋나기 때문에 사용자는 기록이 망가진 걸 나중에야 안다. 따옴표·줄바꿈·BOM·CRLF를 모두 처리하고, FitNotes(안드로이드/iOS 두 헤더)·Strong·Hevy의 열 이름을 별칭 표로 매핑한다.

⑧ 관리자 권한과 초대 코드

const ADMIN_UIDS = (process.env.ADMIN_UIDS || '').split(',').map(s => s.trim()).filter(Boolean);
const isAdmin = user => !!user && (user.admin === true || ADMIN_UIDS.includes(user.id));

권한 판정이 서버에서 강제되고, 프론트의 <Route path="/admin"> 가드는 화면을 숨기는 역할만 한다. 이 구분을 헷갈리면 그대로 보안 구멍이 된다.

초대 코드는 randomBytes(8) = 64비트다. 주석에 왜 이 길이인지가 적혀 있다 — 이 앱에는 요청 한도 제한이 없고 가입 옵션 요청이 "코드가 맞는지"를 알려 주는 통로가 되므로, 코드 자체가 무차별 대입으로 못 맞출 만큼 길어야 한다는 것이다. 없는 방어를 다른 방어로 메운 사례다.

⑨ 코드 중복을 일부러 남긴 자리

server.js와 lib/history.js에 같은 일을 하는 작은 함수(effectiveRoutineId)가 두 번 쓰여 있다. 주석에 이유가 있다 — "두 런타임 사이에 공유 인프라를 만들 만큼 큰 함수가 아니다." 공유하려면 별도 패키지든 빌드 설정이든 구조가 하나 늘어난다. DRY가 항상 이기는 규칙은 아니라는 것을, 근거와 함께 남겨 둔 사례다.

7하드웨어 · 시스템 요구사항

서버 쪽

가장 중요한 요구사항은 성능이 아니라 HTTPS다

환경 변수 전체

클라이언트 쪽

• 웹(PWA) — 패스키·서비스 워커·Wake Lock을 지원하는 최신 브라우저. 홈 화면에 추가하면 앱처럼 뜬다.
• 안드로이드 — 사이드로딩용 APK(플레이스토어 미등록). 서버 없이 폰 안에서만 도는 버전이다.
• iOS — 스토어 앱 없음. 자가호스팅 후 사파리에서 홈 화면에 추가(PWA)하거나 Xcode로 직접 빌드해야 한다. 사본의 frontend/ios/는 비어 있어서 후자는 손이 더 갈 것으로 보인다.

백업 — 이게 전부다

./data/
  secret            서명 키   ← 지우면 전원 로그아웃(재로그인은 가능)
  db.json           계정 · 패스키 공개키 · 푸시 구독 · 초대코드
  state-<uid>.json  사람마다 하나. 계획 · 운동기록 · 체중 · 설정
  vapid.json        푸시 키 쌍

→ 이 폴더만 복사하면 백업 끝. DB 덤프 명령 같은 건 없다.

패스키의 개인키는 서버에 없다. 폰의 보안 칩(또는 비밀번호 관리자) 안에 있고, db.json에는 공개키만 있다. 서버 파일이 통째로 유출돼도 로그인할 수는 없다. 물론 운동 기록은 평문이니 그건 별개로 보호해야 한다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

1주차 · 서버의 밑바닥

• Node의 http 모듈: 요청·응답 스트림, 헤더, 스트리밍 본문 읽기
• 쿠키와 서명: HMAC이 무엇을 보장하고 무엇을 보장하지 않는가(위조 방지 ≠ 암호화)
• SameSite·HttpOnly·Secure 세 플래그가 각각 막는 공격
• 실습 — server.js를 읽고 엔드포인트 목록과 인증 필요 여부를 표로 정리

2주차 · 패스키(WebAuthn)

• 공개키 암호의 최소 개념: 서명과 검증, 개인키가 기기를 안 떠난다는 의미
• RP_ID·origin·챌린지가 각각 무엇을 막는가(피싱 방어의 원리)
• discoverable credential(residentKey)과 아이디 없는 로그인
• 실습 — 로그인 과정을 네트워크 탭으로 따라가며 챌린지와 서명이 오가는 걸 관찰

3주차 · 오프라인 우선 프론트엔드

• 서비스 워커 수명 주기와 캐시 전략 세 가지(cache-first / network-first / stale-while-revalidate)
• Zustand + localStorage 지속화, 디바운스 동기화, 더티 플래그
• PWA 설치, manifest.json, 홈 화면 추가
• Wake Lock·Page Visibility API처럼 브라우저가 마음대로 회수하는 자원 다루기
• 실습 — 개발자 도구에서 오프라인으로 전환한 뒤 기록하고, 다시 연결했을 때 동기화되는지 확인

4주차 · 배포와 도메인 모델링

• 도커 멀티스테이지 빌드, BUILDPLATFORM과 멀티 아키텍처
• nginx 리버스 프록시, SPA 폴백, 캐시 헤더 설계
• Web Push와 VAPID, 시간대를 다루는 스케줄링(Intl.DateTimeFormat)
• 순수 함수로 도메인 규칙 격리하기 + Vitest로 근거 남기기
• 실습 — 8절 과제 2를 마무리하고, 만든 정책의 근거를 테스트로 문서화

10핵심 키워드 사전

인증 · 보안

구조 · 운영

프론트엔드

운동 도메인

11참고 링크

저장소

• arvids-unavailable/openGym — 이 문서가 읽은 사본(TrendShift 목록에 오른 주소)
• hasaneyldrm/exercises-dataset — 운동 1,324개의 원본 데이터셋. 이쪽은 살아 있다
• AGPL-3.0 원문 — 고쳐서 서비스로 돌리면 그 소스도 공개해야 하는 라이선스

저장소 안에서 읽을 순서

1. api/server.js — 554줄. 서버 전체
2. frontend/src/lib/progression.js + progression.test.js — 도메인 규칙과 그 근거
3. frontend/src/store/useStore.js — 로컬 우선 동기화
4. docker-compose.yml · nginx.conf — 세 컨테이너를 한 주소로
5. frontend/src/lib/i18n.js · wakelock.js — 라이브러리 없이 푸는 작은 문제 둘
6. CHANGELOG.md — 원본 이력이 남은 유일한 파일
7. docs/SELF_HOSTING.md — HTTPS·RP_ID 설정의 실제 함정

기술 문서

• webauthn.guide — 패스키 흐름을 그림으로 설명한 입문서
• SimpleWebAuthn 문서 — 이 저장소가 쓰는 라이브러리
• MDN · Web Authentication API
• MDN · Push API · Screen Wake Lock API
• Node.js http 문서 — 프레임워크가 감춰 주던 것
• Zustand 문서 · Vitest · Vite
• Capacitor 문서 — 웹 앱을 네이티브로 감싸기
• Docker 멀티 플랫폼 빌드 — BUILDPLATFORM 함정의 배경