KanaDojo かな道場 딥다이브
— 듀오링고를 닮은 일본어 학습 도장

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

KanaDojo(저장소명 lingdojo/kana-dojo, 서비스명 かな道場)는 세 개의 도장(Dojo)으로 나뉜다. Kana 도장은 히라가나·가타카나, Kanji 도장은 JLPT N5~N1 한자, Vocabulary 도장은 어휘를 다룬다. 각 도장에서 글자/단어 묶음을 고른 뒤 게임 모드를 선택하면 훈련이 시작된다. 회원가입·서버 계정이 필요 없고, 진행 상황과 설정은 모두 브라우저(localStorage)에 저장되는 100% 클라이언트 학습 도구다.

차별점은 '학습'보다 '경험'에 있다. 4가지 게임 모드(Pick·Reverse-Pick·Input·Reverse-Input)에 더해 시간제한 Blitz, 목숨이 걸린 Gauntlet, 정신없는 CrazyMode까지 있고, 100+ 테마 · 28종 일본어 폰트 · 80+ 업적으로 자기 화면을 끝없이 꾸밀 수 있다. 코드 관점에서는 "학습 콘텐츠 데이터 + 게임 엔진 + 극한의 커스터마이즈 UI"를 깔끔한 레이어로 쌓아 올린 모던 Next.js 앱이다.

2왜 주목받는가

트렌딩 이유 · 경쟁 대비 장점.

일본어 학습 앱은 듀오링고·Anki·WaniKani 등 강자가 즐비하다. 그런데도 이 레포가 TrendShift 상위에 오른 이유는 세 가지다. 첫째, Vercel OSS 후원 + "good first issue" 친화라 오픈소스에 처음 기여하려는 개발자들의 유입 거점이 됐다. 둘째, 코드가 최신 스택(Next.js 16 · React 19 · Tailwind 4)의 살아있는 예제라 프론트엔드 학습 교재로 가치가 크다. 셋째, 몽키타입식 극한 커스터마이즈가 "공부 앱인데 꾸미는 재미가 있다"는 입소문을 만든다.

3기술 스택 전체 지도

'일본어 학습 게임'을 떠받치는 기술들.

KanaDojo는 백엔드 서버가 거의 없는 프론트엔드 집약형 100% TypeScript 앱이다. Next.js 16 App Router로 라우팅·SSR·SEO를 처리하고, 상태는 Zustand(localStorage 영속화)로 관리한다. 일본어 텍스트 처리는 전용 라이브러리(kuroshiro·wanakana)에 맡기고, 사전 데이터는 SQLite를 브라우저에서 직접 굴린다.

4아키텍처 심화 분석

시스템 구조도 · 핵심 설계 패턴.

KanaDojo의 핵심 설계는 Feature 기반(Feature-Sliced 유사) 레이어 아키텍처다. 코드를 "컴포넌트/스토어/데이터" 같은 기술 종류로 나누지 않고, "Kana/Kanji/Vocabulary/Progress" 같은 기능 단위로 자른다. 그리고 레이어를 위→아래 한 방향으로만 의존하게 강제해, 기능끼리 서로의 내부를 침범하지 못하게 한다.

레이어 의존 방향 (위에서 아래로만)

설계 패턴 ① — Facade(공개 입구) 패턴

각 기능 폴더에는 facade/ 또는 index.ts라는 '정문'이 있다. 바깥에서는 이 정문이 내보낸 것만 쓸 수 있고, 폴더 안쪽의 컴포넌트·스토어 파일을 직접 가져다 쓰면 안 된다. 예를 들어 Kana 기능은 features/Kana/facade/에서 useKanaContent·useKanaSelection만 공개하고, 내부의 useKanaStore나 게임 컴포넌트는 숨긴다. 덕분에 내부 구현을 바꿔도 바깥 코드가 깨지지 않는다.

// entities/kana/index.ts — 도메인의 공개 입구(정문)
export { kana } from '@/features/Kana/data/kana';
export type { KanaGroup } from '@/features/Kana/data/kana';
export { flattenKanaGroups } from '@/features/Kana/lib/flattenKanaGroup';
export { getSelectionLabels } from './selection';
// 바깥(widgets·app)은 이 파일만 import → 내부 파일 경로는 자유롭게 변경 가능

설계 패턴 ② — Zustand 스토어를 '기능별'로 쪼개기

전역 상태를 거대한 하나의 store에 몰지 않고, 기능마다 작은 store를 둔다. useKanaStore(선택한 글자 묶음·게임 모드), useStatsStore(통계·업적), usePreferencesStore·useCustomThemeStore(테마·폰트·월페이퍼)처럼 책임이 분리돼 있다. 그리고 통계·설정처럼 오래 남겨야 하는 상태는 persist 미들웨어로 localStorage에 자동 저장한다.

// features/Progress/store/useStatsStore.ts (요지)
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';

const useStatsStore = create(
  persist(
    (set) => ({
      allTime: { totalCorrect: 0, bestStreak: 0 /* … */ },
      recordAnswer: (ok) => set(/* 정답/오답 집계 */),
    }),
    { name: 'stats', storage: createJSONStorage(() => localStorage) } // ← 브라우저에 영속
  )
);

설계 패턴 ③ — 학습 콘텐츠 = 순수 데이터, 출제 = 순수 함수

가나·한자·어휘는 features/*/data/에 순수 데이터(JSON/TS 배열)로 담겨 있고, "다음 문제를 무엇으로 낼까"는 lib/의 순수 함수가 결정한다. 부작용(화면 그리기·저장)과 계산(출제·정답 판정)을 분리했기 때문에, 출제 로직만 떼어 내 단위 테스트할 수 있다(실제로 generateKanaQuestions·isKanaInputAnswerCorrect 테스트가 있다).

// features/Kana/lib/generateKanaQuestions.ts — 편향 없는 무작위 출제
import { Random } from 'random-js';
const random = new Random();

export function generateKanaQuestion(selected: KanaCharacter[]): KanaCharacter {
  if (selected.length === 0) throw new Error('No kana selected');
  const i = random.integer(0, selected.length - 1); // random-js: 균일 분포
  return selected[i];
}

5디렉토리 구조 해부

주요 폴더·파일의 역할.

주목할 점 몇 가지. app/[locale]/의 대괄호는 Next.js의 동적 라우트로, URL의 언어 코드(en·es)를 변수처럼 받는다. train/ 페이지에서 게임 모드(Pick·Input 등)는 URL 세그먼트가 아닌 클라이언트 상태로 처리하고, 시간제한 모드는 train/timed/ 서브라우트를 별도로 사용한다. proxy.ts는 예전 Next.js의 middleware.ts에 해당하는 파일(최신 명명 규약)로, 들어오는 요청의 언어를 감지해 알맞은 로케일 경로로 보내는 관문 역할을 한다.

또 하나, scripts/가 유난히 풍부하다. 번역 키 누락 검사(i18n:validate), 타입 자동 생성, Anki 변환, 월페이퍼 이미지 처리, SEO 헬스체크, 번들 크기 점검까지 — "손으로 반복할 일은 전부 스크립트로"라는 성숙한 OSS 운영 문화를 보여 준다.

6학습 포인트 (기술별)

이 레포에서 무엇을, 어떻게 배울 수 있나.

7시스템 요구사항

직접 돌려 보려면 무엇이 필요한가.

이용자 입장에선 설치가 전혀 필요 없다. kanadojo.com에 접속만 하면 되고, 모든 진행상황은 브라우저에 저장되므로 계정도 필요 없다. 개발자로서 코드를 돌려 보려면 Node 20과 위 명령이면 충분하다.

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

난이도별로 손을 움직여 보자.

🟢 입문 ★☆☆☆☆ · 환경 적응

① 로컬 실행 + 테마 하나 추가. 레포를 클론해 npm run dev로 띄운 뒤, features/Preferences/data/themes/themeDefinitions.ts에 내 색조합 테마를 하나 추가하고 화면에서 선택해 본다. "데이터를 바꾸면 UI가 바뀐다"는 데이터 주도 설계를 체감하는 과제.

🟢 초급 ★★☆☆☆ · 데이터 읽기

② 가나 데이터 구조 분석. features/Kana/data/kana.ts와 lib/flattenKanaGroup.ts를 읽고, '그룹(행) → 개별 글자'로 펼치는 흐름을 그림으로 정리한다. 그런 다음 탁음·요음 한 그룹이 빠졌다고 가정하고 데이터에 추가해 본다.

🟡 중급 ★★★☆☆ · 로직 + 테스트

③ 채점 함수에 테스트 추가. features/Kana/lib/isKanaInputAnswerCorrect.ts를 읽고, 장음(ー)·n받침(ん)·대소문자 같은 엣지 케이스에 대한 Vitest 케이스를 직접 작성한다. npm run test:watch로 빨강→초록을 만든다.

🟡 중상급 ★★★★☆ · 기능 확장

④ 새 게임 모드 한 판 만들기. 기존 Pick/Input을 참고해 "음성 듣고 고르기" 같은 새 모드의 뼈대를 features/Kana/components/Game/에 추가하고, train/ 페이지의 클라이언트 상태와 연결한다. Facade·store 규칙을 지키며 기능을 끼워 넣는 연습.

🔴 고급 ★★★★★ · 인프라/아키텍처

⑤ 한국어 로케일 풀스택 적용. routing.ts에 ko 추가 → locales/ko.json 작성 → i18n:check로 누락 키 0 만들기 → 미들웨어 동작 확인 → 메타데이터/사이트맵까지 한국어가 반영되는지 점검한다. 다국어 시스템 전체를 관통하는 종합 과제.

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

4주에 걸쳐 이 레포를 '내 것'으로.

10핵심 키워드 사전

한 줄로 빠르게 짚는 용어.

11참고 링크

• GitHub: lingdojo/kana-dojo
• 실제 서비스: kanadojo.com
• 코드 문서(DeepWiki): deepwiki.com/lingdojo/kana-dojo
• Next.js 문서: nextjs.org/docs
• Zustand: github.com/pmndrs/zustand
• next-intl: next-intl.dev
• wanakana: github.com/WaniKani/WanaKana
• 영감: Duolingo · Monkeytype