Hub

普段は製造現場で働いていて、開発は休日と平日の夜に少しずつ進めています。 設計書を先にがっちり作るより、動く画面を出して触りながら直す方が自分には合っている。 Hubもそうやって育ったので、ところどころは雑です。

このページは、同じように小さなWebアプリを作っている人の参考になればと思って書きました。 きれいな完成像より、詰まった場所と直し方を残しています。

きっかけはMapifyです。無料で使ってみたら、1回でその日の利用が終わってしまった。 「もう一回、別のテーマでも試したい」と思ったときに使えないのが惜しくて、 それなら自分で作った方が早いと思いました。

その後、本格的なマインドマップツールとしてXmindなどの存在も知りましたが、 Hubは「自分が頭の中を整理したいときに、気兼ねなく何度でも使える簡易版」という位置づけで、 個人開発のおもちゃとしてそのまま育てています。

パスワードを付けたのは、公開したあとに勝手に使われると困るからです。 APIの無料枠は自分の用途のために使いたいし、知らないところで消費されると、 作り直す気力ごと削られます。

このページを公開したのは、設計の判断を残しておきたかったから。 あと、作ったものを見てもらう入口がひとつ欲しかった。 それくらいの理由です。

画面は1枚だけです。サーバーはAIを呼んでJSONを返す役割に絞って、 マップの状態はブラウザの localStorage に保存しています。 データベースは使っていません。

やり取りするJSON

AIと画面の間で行き来するのは、text と children だけです。 IDや開閉状態はブラウザ側で付けるので、サーバーはツリーの形だけを返します。

{
  "items": [
    {
      "text": "サブテーマ",
      "children": [
        {
          "text": "要素",
          "children": [
            { "text": "補足" }
          ]
        }
      ]
    }
  ]
}

リクエストとレスポンス

POST /（Hubの生成エンドポイント）
Content-Type: application/json

{
  "text": "新しいカフェの開業",
  "mode": "generate"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    { "text": "コンセプト", "children": [] }
  ]
}

エラーは {"error": "..."} で返します。 入力不正は400、未ログインは401、生成元が違うときは403、本文が大きすぎるときは413、 混雑・上限は429、候補が全部だめなら502です。

生成が始まってからJSONが返るまでの流れです。 外部APIに届く前に落とせるものは、できるだけ手前で落とします。 無料枠は有限なので、明らかに無駄なリクエストで消費したくないからです。

1. 1
   ブラウザ

   テーマとモードをJSONでPOSTする。描画はそのあと全部ブラウザ側。

2. 2
   ログイン・CSRF・レート制限

   未ログインのPOSTはここで401。Originのホストとポートも照合する。同じIPから10回/分を超えたら429。

3. 3
   入力の形をそろえる

   本文4KB、JSONの型、テーマ50文字、モードの種類をチェック。変な値はAIに渡す前に落とす。

4. 4
   キャッシュを見る

   プロンプト版・モード・テーマのSHA-256で900秒キャッシュを確認。同じテーマの連打ではAPIを叩かない。

5. 5
   同時実行を1本に絞る

   ファイルロックで待たせる。同時に2本走ると無料枠を一気に食うため。待ち時間は最大15秒。

6. 6
   候補を順に試す

   使えるプロバイダとモデルを優先度とLRUで並べ、最大5回まで試す。ダメなら次へ。

7. 7
   出力を検査する

   コードフェンスを外してJSONを取り出し、深さ4・100ノード・50文字の上限をかける。壊れていたら別候補へ。

8. 8
   描画する

   サブツリーの高さから座標を決めて、SVGの線とDOMのノードを出す。ここはサーバーではなくブラウザの仕事。

ここからは実装の話です。擬似コードは実際のコードを短くしたもので、 そのまま動くものではありません。

function calculateSubtreeHeights(node):
    if node has no visible children:
        node.height = NODE_HEIGHT
        return node.height

    total = sum(calculateSubtreeHeights(child) + GAP_Y for child in children)
    total -= GAP_Y
    node.height = max(NODE_HEIGHT, total)
    return node.height

function assignCoordinates(node, x, bandTop):
    node.x = x
    node.y = bandTop + (node.height - NODE_HEIGHT) / 2

    currentY = bandTop
    for child in visible children:
        assignCoordinates(child, x + NODE_WIDTH + GAP_X, currentY)
        currentY += child.height + GAP_Y

最初はAPIキーをHub本体に直書きしていました。 500で落ちたときにソースを開いて、これはまずいと気づいたのがきっかけです。 そこからキーを非公開の設定ファイルに移しました。 キーは、漏れた可能性があると思ったらすぐ作り直す前提です。

パスワードは後から付けました。作った当初は自分しか使わないつもりだったけど、 公開したらそうとも限らない。勝手に使われてAPI枠が減るのは嫌なので、 ログインと試行回数の制限を足しました。

あとから、URLにフォルダ名を直接入れられても中身が見えないようにしました。 フォルダの中身を一覧表示できないようにして、設定ファイルとAI用のライブラリは Webから直接開けない設定にしています。

うまくいったことだけ並べても仕方ないので、詰まったところを残します。

500で落ちた

トップページがHTTP 500で真っ白になりました。 原因はPHPの構文エラーで、$apiKey の代入が二重に書かれていた箇所と、 || が \vert{}\vert{} に化けていた箇所でした。 エラーログを見るまで「サーバー側の問題だろう」と思っていて、自分のコードを疑っていませんでした。

直すついでに、切れていたJavaScriptの後半も復元しました。 動いているように見えても、ファイルの末尾が切れていることがあるんだな、というのがその日の学びです。

ノードが重なった

階層を増やすと、ノードが見えなくなる場所と重なる場所が出ました。 最初は「画面が狭いから仕方ない」と思っていたけど、原因は配置の計算でした。 子ノードをサブツリーの上端に置いていたので、深い階層ほど親が上にずれていた。 中央揃えに直したら、86ノードでも重ならなくなりました。

セキュリティは後回しにしていた

最初は動かすことで精一杯で、APIキーの直書きも、TLS証明書の検証を切っていたことも、 後から気づきました。機能を作ったあとにまとめて直すと、確認する範囲が広くて大変です。 次に作るときは、キーの置き場所だけは最初に決めようと思っています。

429はまだ起きていない

レート制限は「そのうち起きるだろう」と思って対策しましたが、実際にはまだ起きていません。 起きていないのにキーを50個集めるのは、たぶん順番が逆です。 まずは利用回数を記録して、429が出たときにどの無料枠が減っているかを見る。 それからキーを増やすか、有料枠を考える。いまはそう考えています。

まだ直していないこと

• マップはブラウザごとの保存で、端末間の同期はない
• 同時実行を1本に絞っているので、複数人で使うと待つ
• ノードが多いときの表示仮想化は未実装
• ファイルベースの状態管理なので、サーバーを分けると成り立たない
• AI出力の偏りや内容の正しさは保証できない

試したこと

• 429 → 次の候補へ移り、クールダウンが記録される
• 401 / 403 → そのキーを1時間無効にして次へ
• 5xx・タイムアウト・不正JSON → 次へ進み、全滅時は502
• 同じテーマの再生成でキャッシュが返り、APIを呼ばない
• 同時実行が1本に制限され、待ちすぎると429
• 深さ4・100ノード・50文字の上限がかかる
• 未ログインの生成と状態確認が401になり、状態のJSONにキーが出ない
• 実APIで初回11ノード / 3階層、深掘り4ノード / 1階層
• 86ノードの密集ツリーで重なり0件

分かる範囲で、やったことを並べておきます。

1. セキュリティをまとめて直す

   最初は、PHPに直書きしていたAPIキーを非公開の設定ファイルへ分離、TLS検証の有効化、CSP、レート制限、入力上限を追加。

2. 見た目と階層を調整

   初回は3階層・10〜12ノード、深掘りは1階層・3〜4ノードに変更。色分けとズームも追加。

3. 重なりを直す

   サブツリー中央揃えに変更。固定キャンバスをやめて、ノード数に応じて広げるようにした。

4. ログインを追加

   ログイン画面、セッション、CSRF、ログイン試行の制限。初期パスワードを発行して終了。

5. AI呼び出しを分離

   AI呼び出し用の別ファイルに候補選択、キャッシュ、同時実行制限、フォールバックを実装。

6. この設計メモを追加

   仕様と失敗談を公開用のページにまとめた。スクリーンショットもここで撮り直した。

次にやること

まずは利用回数と429の内容を記録すること。 どのモデルがどれくらい使われたか見えるようにして、必要ならキーを増やす。 余裕が出たら、状態管理をSQLiteに移すか、大きいマップの描画を軽くするかを考えます。 全部やるかは分かりません。まずは429が起きたときに困らないところからです。

ファイルの役割

画面と認証は1つのファイルにまとめて、AI呼び出しだけ別ファイルに分けました。 プロバイダを増やすときは設定配列に足すだけで、画面側は触らなくて済みます。 最初からこうしていたわけではなく、キーが増えそうになってから分けた形です。