Kanji Otter

1. 全体の構成 Architecture

学習データはまずiPhoneの中に保存され、オフラインでも使えます。アカウントとクラウド保存はAzure、課金はApple、広告と分析はGoogleが担当します。
Progress lives on the iPhone first, so the app works offline. Azure handles accounts and cloud save, Apple handles payments, Google handles ads and analytics.

2. アカウントとクラウド保存 Accounts & cloud save

登録しなくてもすぐに使えて、あとからメールでアカウントを作れる「匿名ファースト」の設計です。
"Anonymous first": no sign-up needed to start, an email account can be added later.

1. 初回起動 First launch アプリが匿名アカウントとランダムな秘密鍵（256ビット）を作り、Keychainに保存。 The app creates an anonymous account and a random 256-bit secret, stored in the Keychain.
2. 自動保存 Auto save 許可リストにあるデータだけを送信。サーバーは秘密鍵のハッシュ（SHA-256）しか持ちません。 Only whitelisted progress keys are sent. The server only keeps a SHA-256 hash of the secret.
3. アカウント連携 Link an account Entra External IDでメール＋パスワードを登録。APIがトークン（JWT）の署名を検証します。 Email + password through Entra External ID. The API verifies the JWT signature, issuer and audience.
4. 機種変更 New phone ログインすると進捗が戻ります。万一のために、時間をおいたバックアップも残します。 Sign in and progress comes back. A time-delayed backup copy protects against mistakes.

3. 学習の流れ Learning loop

「覚える → 試す → 忘れる前に復習する」を、ゲームの冒険にのせて続けられるようにしました。
"Learn → test → review before you forget", wrapped in an adventure so learners keep coming back.

4. 収益化 Monetization

無料でも学び続けられることを大切にしました。制限があるのは一部のモードだけです。
Learning must stay possible for free: only some modes have a limit.

5. 設計で考えたこと Design decisions

• オフラインファースト — 電車の中でも使えるように、データは端末に保存。 Offline first — progress stays on the phone so the app works on the train.
• パスワードを自分で持たない — 認証はMicrosoft Entra External IDに任せ、サーバーはトークンを検証するだけ。 No passwords on my server — Entra External ID handles sign-in, the API only verifies tokens.
• 秘密はKeychainに — UserDefaultsではなくKeychain。暗号化されていないバックアップから読めないようにするため。 Secrets in the Keychain — not UserDefaults, so they can't be read from an unencrypted backup.
• 許可リスト方式の同期 — 新しいデータは明示的に追加しない限り送信されません。 Whitelist sync — new data is never uploaded unless explicitly added to the list.
• アカウント削除 — Appleの審査ルールに合わせ、保存データとディレクトリ上のアカウントを両方削除。 Account deletion — per App Store rules, both the save data and the directory account are deleted.

チュートリアル Tutorial

最初のゲームは案内つき。画面を少しずつ照らし、今さわるべきボタンだけを見せます。辞書などの説明は、その機能を初めて使うときに表示。毎日のまとめやストリークの通知は、チュートリアルが終わるまで待ちます。
The first game is guided: the screen is revealed step by step, highlighting only the button to tap next. Feature tips (like the dictionary) appear the first time you use them. Daily recaps and streak alerts wait until the tutorial is over, so new players are never overwhelmed.

ゲーミフィケーション Gamification

いろいろな練習で飽きないようにしています：選択クイズ、落ちてくる音符、なわとび、リズムゲーム、ボス戦、JLPT模試。
Many exercise types keep it fresh: multiple-choice quizzes, falling notes, jump rope, a rhythm game, boss battles and a JLPT mock exam.

ごほうびは4つの時間軸で設計しました。Rewards are designed on four time scales:

1. すぐ Instant 正解ごとにカワウソが登場して反応。連続正解でコンボ、たまにレアなカワウソも。 Every right answer brings an otter that reacts; streaks of answers build a combo, and a rare otter shows up now and then.
2. 今日 Today 一日のまとめと王冠、毎日のストリーク、そして川のミッション（ポイント、連続日数、カワウソの数など）。 A daily recap with crowns, a day streak to keep alive, and river missions (points, streak days, otters on screen…).
3. 数週間 Weeks 278ステップの川を進み、ボスを倒して、日本の観光地を集める。 Travel along a 278-step river, beat bosses and unlock Japanese travel spots.
4. 数か月 Months JLPTのレベルを上げ、模試に合格し、90日後の復習まで覚え続ける。 Climb the JLPT levels, pass the mock exam, and still remember kanji at the 90-day review.

6. 学んだこと What I learned

一番難しかったのは、ユーザーが実際にどう操作するかを理解することです。何を読み、何を読み飛ばすか。小さなつまずきで迷ったり、やめてしまったりする場面をひとつずつ減らしています。
The hardest part was understanding how people really use the app: what they read, what they skip, and the small blockers that make them feel lost or quit. I keep removing them one by one.