NARITAIの技術構成について
今回の記事は、かなりソフトウェアエンジニア目線で書いています。
Claude CodeやCodexのようなAIコーディングツールによって、非エンジニアでも動くソフトウェアを作れる時代になりました。一方で、「なぜその技術を選ぶのか」「どこに何を任せるのか」「将来の運用まで考えると何を分けるべきなのか」は、動くものを作るだけでは見えにくい部分です。
この記事では、本職のソフトウェアエンジニアがNARITAIの技術構成をどう考えているか、その理由をできるだけそのまま書きます。今読んでも意味が分からない箇所があるかもしれません。ただ、後から読み返して理解できる部分が増えていたら、それは技術を見る目が育っている証拠だと思います。
NARITAIは、中小企業診断士試験の学習を支えるWebアプリです。一次試験では過去問・解説・教科書コンテンツを配信し、二次試験では答案の保存、模範解答の確認、AI添削までを扱います。
この記事では、NARITAIをどのような構成で作っているか、なぜその技術を選んでいるかを整理します。単に使っているサービスを並べるだけではなく、試験学習アプリとして必要になる「大量の静的コンテンツ」「ユーザーごとの学習履歴」「AI添削」「課金」をどう分けているかを中心に書いていきます。
ざっくりとした構成
主な使用技術やサービスは以下のようになっています。
React Router: フロントエンドアプリ
Hono: Backend API
Cloudflare Workers: フロントエンドとバックエンドの実行環境
Cloudflare Queues: 二次試験AI添削ジョブの非同期処理
Cloudflare R2: 過去問、解説、教科書、画像などの静的コンテンツ配信
Turso: ユーザー情報、学習履歴、課金状態などの動的データ
Gemini Developer API: 二次試験答案のAI添削
Stripe: 有料プラン、Checkout、Customer Portal、Webhook
pnpm workspace: frontend / backend を分けたモノレポ管理
Vitest / React Testing Library: テスト
大きくは「静的コンテンツはR2」「動的なユーザーデータはTurso」「AI添削はGemini」「重い添削処理はCloudflare Queues」「課金はStripe」「APIはWorkers上のHono」という分担です。
モノレポ構成
リポジトリはpnpm workspaceを使ったモノレポです。現在は大きく `frontend` と `backend` に分かれています。
`frontend`: React Routerで作っているWebアプリ
`backend`: Honoで書いているAPI
`scripts`: R2反映、画像変換、カテゴリインデックス生成などの運用スクリプト
`exam`: 一次試験・二次試験の問題、解説、教科書などの編集用原本
`docs`: 仕様書、運用メモ、リリースチェックリスト
NARITAIでは、アプリ本体のコードだけでなく、試験コンテンツそのものもリポジトリで管理しています。特に一次試験の過去問、解説、教科書は量が多く、アプリの実装とコンテンツ生成・配信の運用を切り離しすぎるとかえって扱いづらくなります。
そのため、編集用の原本はリポジトリに置き、公開時はR2へ反映する形にしています。コードとコンテンツの距離を近くしておくことで、表示仕様や配信仕様を変えたときに、対象データも同じPRで確認しやすくなります。
フロントエンド
フロントエンドはReact Routerを使っています。一次試験の演習画面、教科書閲覧、二次試験の答案入力、マイページ、課金画面などを担当します。
一次試験の教科書は、VitePressやDocusaurusのようなドキュメントサイトに近い体験を目指しています。左側に文書ツリー、中央に本文、右側にページ内目次を置き、ユーザーが検索結果やブックマークから直接トピック単位で戻ってこられる構成です。
本文はMarkdownをベースにしつつ、数式はKaTeX、表や強調はMarkdownで表現しています。試験対策の教材では、文章、表、数式、図解が混ざります。画面側ではこれらを自然に読めるようにしつつ、初期表示の重さが出ないよう、二次試験専用UIや大きな補助データは必要になったタイミングで読み込む方針にしています。
バックエンド
バックエンドはHonoで書き、Cloudflare Workers上で動かしています。
Honoを使っている理由は、Workersとの相性がよく、APIを薄く保ちやすいからです。NARITAIでは、過去問取得、解説取得、教科書取得、認証、学習履歴、課金、AI添削など、性質の異なるAPIが同居しています。フレームワーク側の厚い抽象よりも、リクエストとレスポンスの境界を見通しやすい構成のほうが合っています。
また、Cloudflare Workersを使うことで、R2やCache APIと近い場所で処理できます。教科書や画像のような静的コンテンツはR2から読み、Worker側でキャッシュヘッダーや公開パスの制御を行います。単純なファイル配信ではなく、公開してよいパスや拡張子をAPI側で絞ることで、運用ミスの影響を小さくしています。
静的コンテンツはR2に置く
NARITAIで一番量が多いのは、ユーザーごとのデータではなく試験コンテンツです。
一次試験の問題JSON
一次試験の解説JSON
教科書Markdown
教科書画像
二次試験の問題、模範解答、共通解説
法務文書のMarkdown
これらは頻繁にユーザーが更新するものではありません。一方で、画面からは何度も読まれます。そのため、DBに入れるのではなく、編集用原本をリポジトリで管理し、公開用のMarkdown、JSON、JPG、AVIFをR2へアップロードする形にしています。
教科書画像は、PNGをローカル原本として残し、配信用にはJPGとAVIFを使います。MarkdownではAVIFを優先し、JPGをフォールバックにします。これにより、教材画像の品質を保ちながら、配信時のサイズを抑えています。
教科書本文や画像はCloudflare Cacheも使います。本文は更新反映性を残すため短めに、画像は長めにキャッシュします。教材は一度公開すると多くのユーザーが同じ内容を読むため、R2の読み取り回数を抑えることはコスト面でもレスポンス面でも効きます。
動的データはTursoに置く
ユーザーごとに変わるデータはTursoに保存します。
認証ユーザー
プロフィール
学習履歴
演習結果
二次試験答案の提出履歴
課金状態
AI添削の利用回数
R2に置くデータとTursoに置くデータを分けているのは、読み取り方と更新頻度がまったく違うからです。
過去問や教科書は、全ユーザーにほぼ同じものを配ります。一方で、学習履歴や課金状態はユーザーごとに更新され、権限判定にも関わります。この2つを同じ保存先に寄せると、実装も運用も複雑になります。
NARITAIでは、静的な教材はR2、ユーザーにひもづく状態はTursoという分け方にしています。Cloudflare WorkersからHTTP経由で扱いやすく、SQLiteベースでローカル開発時の見通しもよい点がTursoの使いやすいところです。
認証は自前実装
認証は、当面Googleログインを本番の唯一のログイン手段としています。IDaaSを使わず、Cloudflare WorkersとTursoを使って必要な範囲を自前で実装しています。
この判断は、機能を増やしたいからではなく、必要な認証体験を絞るためです。NARITAIの本番ログインはGoogleに限定し、Apple IDログインや開発用モック認証は本番経路に混ぜません。ログイン手段を増やすよりも、課金・学習履歴・AI添削の権限判定を確実に保つことを優先しています。
二次試験のAI添削
二次試験のAI添削にはGemini Developer APIを使っています。
ただし、答案をそのままLLMに投げて点数まで自由に決めさせる構成にはしていません。NARITAIの添削は、ルールベースの採点レイヤーとLLMによる講評レイヤーを分けています。
ルールベース: キーワード、制約、配点、計算結果などを安定して判定する
LLM: 与件活用、因果関係、答案の改善点を自然文で説明する
点数と講評を分ける理由は、診断士二次試験の学習で「キーワードさえ入れればよい」という誤学習を避けるためです。点数はできるだけ再現性を持たせ、LLMにはその点数の理由や改善の方向を説明させます。
添削結果はR2にも保存します。結果参照APIではGeminiを呼ばず、保存済み結果を返すだけにしています。提出時にだけAIを実行し、結果画面を開くたびに再添削が走らないようにするためです。これはコスト制御だけでなく、ユーザーが同じ答案の結果を安定して見返せるようにするためでもあります。
また、本番環境ではAI添削をHTTPリクエスト中に最後まで実行せず、Cloudflare Queuesにジョブとして投入する構成にしました。提出APIは答案と結果行を保存したうえで `processing` を返し、Queue consumerがGemini呼び出し、R2保存、Turso更新、AI添削利用記録を行います。
この分離により、Geminiの応答に20〜30秒かかる場合でも、ユーザーの提出リクエストが長時間ブロックされにくくなります。大量の添削が同時に発生した場合も、処理待ちはQueueに積まれ、Worker側で順に処理されます。次に注意すべきボトルネックは、Cloudflare Workersのリクエスト時間ではなく、Gemini APIのレート制限や一時的な失敗に対するリトライ設計です。
課金はStripeに寄せる
決済はStripeを使っています。カード情報はNARITAI側では保持せず、CheckoutとCustomer Portalに委譲します。
NARITAI側には、カード番号や有効期限のような決済情報は保存しません。保存するのは「このユーザーは今、有料機能を使える状態か」を判断するための情報だけです。
具体的には、Stripeから同期した購読情報をもとに、次のようなことを見ています。
どのStripe顧客とNARITAIユーザーが対応しているか
現在の契約が月額プランか年額プランか
契約が有効か、解約済みか、支払い失敗中か
今の契約期間がいつ始まり、いつ終わるか
期間終了時に解約予定か
月額から年額への変更予約があるか
AI添削を利用できる有料状態か
ここで大事なのは、「Stripe上の契約が存在すること」と「NARITAI内でAI添削を使わせてよいこと」を分けている点です。
たとえば、ユーザーが解約予約をしていても、すでに支払い済みの契約期間がまだ残っているなら、その期間中はAI添削を使えるようにします。逆に、支払いに失敗して契約が止まっている場合は、Stripeに過去の契約情報が残っていても、NARITAI側ではAI添削を止めます。
つまり、NARITAIでは「支払い済みの期間内か」「支払い状態に問題がないか」「対象プランがAI添削を含むか」を見て、有料機能の利用可否を決めています。決済完了や解約、支払失敗の反映はStripe Webhookを正とし、Checkout後の戻りURLに到達しただけでは有料化しないようにしています。
パフォーマンス面で気をつけていること
NARITAIでは、AI添削のように重い処理もありますが、日常的に一番多く使われるのは教材や過去問の閲覧です。そのため、まず静的コンテンツを軽く配れることを重視しています。
R2とCache APIで教材配信を軽くする
教科書Markdownや画像はR2から配信し、Worker側でCache APIを使います。本文と画像では更新頻度が違うため、キャッシュ方針も分けています。
本文は修正が入ることがあるので短めのブラウザキャッシュにし、Cloudflare側では長めに保持します。画像は本文より更新頻度が低いため、より長くキャッシュします。
配信用画像をJPG / AVIFに変換する
教科書や解説の画像は、生成・編集用にはPNGを残します。ただし、ユーザーに配る画像としてはサイズが大きくなりがちです。
そこで、配信用にはJPGとAVIFを生成し、MarkdownではAVIF優先、JPGフォールバックで表示します。これにより、教材画像を多く含むページでも初期表示の負担を抑えられます。
必要な画面だけ読み込む
一次試験、二次試験、課金、教科書では画面の性質が大きく違います。すべてを初期バンドルに寄せると、最初に開く画面に関係ないコードまで読み込むことになります。
そのため、二次試験専用UIや補助データは必要なタイミングで読み込む方針にしています。特に事例IVのような専用ロジックは、一次試験や通常ページの初期表示に影響させないようにしています。
ローカル開発と本番相当確認
NARITAIでは、作業内容に応じて開発時のデータ参照先を切り替えています。
画面やAPIを作るときは、フロントエンドとバックエンドをローカルで起動する
教科書を直すときは、手元のMarkdownや画像をそのまま画面で確認する
公開前の確認では、R2に置いた教材を本番と同じ経路で読む
課金や外部サービスを触る処理は、必要に応じて副作用を抑えた状態で確認する
教材作成では、Markdownや画像を直しながらすぐ画面で見たい場面があります。一方で、公開前にはR2経由で本番と同じ読み方を確認したい場面もあります。
この2つを同じ仕組みにすると、どちらかが不便になります。そこで、教材作成中は手元のファイルを優先し、公開前の確認ではR2上のファイルを優先するように分けています。これにより、執筆中の修正速度と、本番に近い確認の両方を保てます。
CI/CD
CIはGitHub Actionsを使い、PRとmainへのpushで検証します。現在の最小構成では、依存関係のインストール、カテゴリインデックス生成、バックエンドテスト、ビルドを実行します。
本番デプロイはCloudflare Workersへ行います。順序はbackend、frontendの順です。API契約が変わる場合に、フロントエンドだけが先に新しいAPI前提で動いてしまう状態を避けるためです。
GitHub ActionsからCloudflareへデプロイするため、CIにはCloudflareを操作するためのトークンが必要です。ただし、ここではできるだけ権限を絞ったトークンだけを使い、仮にCI側の情報が漏れてもCloudflareアカウント全体を自由に触れないようにしています。
また、GeminiやStripeなどアプリ本体で使うSecretは、GitHub Actions側に広げずCloudflare側で管理します。CIに持たせる情報は「ビルドして、決められたWorkerへデプロイするために必要なもの」に限定する方針です。
これから改善したいところ
今後の大きなテーマは、運用画面とコンテンツ編集体験です。
現時点では、過去問、解説、教科書の編集用原本はリポジトリで管理しています。この方式は履歴が追いやすく、コードレビューもしやすい一方で、非エンジニアが編集するには重くなります。
そのため、将来的には管理者サイトを用意し、問題・解説・教科書の編集、レビュー、R2反映を段階的にUI化していく予定です。ただし、いきなりすべてをDB管理へ移すのではなく、公開面ではR2配信を維持しながら、編集フローだけを少しずつ改善するのが現実的だと考えています。
NARITAIは、教材配信、学習記録、AI添削、課金が一体になったアプリです。だからこそ、すべてを1つの仕組みに寄せるのではなく、データの性質ごとに置き場所と責務を分けることを重視しています。
静的コンテンツはR2、ユーザー状態はTurso、AI添削はGemini、決済はStripe、APIはWorkers上のHono。この分担を守ることで、機能を増やしても運用しやすい構成にしていきたいと考えています。