Archive

システム構成図

date'2026-08-14'
sourcenull
publictrue

『今のHKDGのシステム構造図。ASCIIアートの罫線だと折り返しで崩れるため、インデント+矢印だけの プレーンテキストで書いてある。

[利用者の端末]
  iPhone(河﨑) / Mac(常時起動、家) / Win機
    ブラウザ、または「アプリとしてインストール」したPWA
    |
    | Tailscale VPN経由でアクセス(外部公開はしていない)
    v
[フロントエンド: digital-garden/frontend]
  React + Vite
  リポジトリ: ~/dev/digital-garden
  役割:
    - 画面(Home / Editor / NoteGallery / Sphere Graph / Playground / VaultTree)
    - 認証状態の管理(ログイン / Semipublicプレビュー)
    - Design System.md・Frontmatter Schema.md・Background.mdを
      「設定データ」としてバックエンド経由で読み書きする
    |
    | REST API(/api/files, /api/search, /api/outlinks, /api/backlinks,
    |          /api/graph, /api/resolve, /api/link-preview, /auth ...)
    v
[バックエンド: webobsidian(フォーク+ローカルパッチ)]
  Node.js、bare-metal起動(Dockerは使っていない)
  リポジトリ: ~/dev/webobsidian(本家からclone、日本語ファイル名/embed解決の
              2件をローカルでパッチ済み、未公開)
  常駐方法: launchd(com.hoda.webobsidian.plist)、RunAtLoad+KeepAlive
  役割:
    - vaultのファイルI/O(読み書き・rename・trash)
    - 検索インデックス(qmd-index.json)・リンクグラフの構築
    - セッション認証(パスワード1つ、requireAuth / optionalAuth)
    - public:trueによる公開/非公開フィルタ
    |
    | ファイルシステム直読み書き(APIやDBを介さない)
    v
[vault本体: ~/ObsidianStorage]
  プレーンなMarkdown + frontmatter。gitは使っていない(2026-07に廃止)
  フォルダ: 0_Inbox 〜 9_Old の番号体系
  「お約束」ノート(このアプリの設定はここに乗っている):
    - 0_Inbox/Design System.md   (配色・タイポグラフィ・グラフの物理パラメータ)
    - 0_Inbox/Frontmatter Schema.md (新規ノートのfrontmatter定義)
    - Background.md              (背景写真の抽選元)
    - 1_Map/Map_*.md              (テーマ分類、リンクベースで所属判定)
    - 0_Inbox/About.md            (Aboutページ)
    |
    | Obsidian Sync(ファイル単位の同期、gitとは別経路)
    v
[もう一方の端末のvaultコピー]
  Win機のObsidianアプリ。webobsidianはMac側の1個だけが直接触っている。
  Win機からはTailscale経由でMac側のwebobsidianにアクセスする形で、
  vaultを直接は読み書きしない(二重書き込みを避けるため)。

補足:

各ユニットの補足説明(初心者向け)

利用者の端末 / Tailscale VPN

普段ブラウザでこのサイトを開いている、そのブラウザ(またはホーム画面に追加したアプリ)のこと。 今このサイトは全世界に公開されたインターネット上には出ておらず、Tailscaleという「自分の持っている 端末同士だけをつなぐ、プライベートな仮想ネットワーク」経由でしかアクセスできない。理由は、家のMacに 直接インターネットから誰でもアクセスできる状態(ポート開放)にすると、そこがセキュリティ上の弱点に なりやすいため。Tailscaleを使うと、自分のiPhone・Mac・Win機の間だけを繋ぐ専用の道ができて、 外部からは道の入口自体が見えない状態にできる。

フロントエンド(React + Vite)

「画面(見た目・ボタン・入力欄)を作っている部分」。ブラウザの中で動くプログラムで、実際のデータ (ノートの中身など)は持っておらず、必要になるたびに下のバックエンドへ「このノートちょうだい」 「これを保存して」とお願いして、返ってきた内容を画面に表示する係。 Reactは画面部品(ボタンや一覧など)を組み立てるための道具(ライブラリ)、Viteはそのプログラムを 開発中に素早く動かしたり、本番用にまとめたりするための道具。どちらも世の中で広く使われている 標準的な技術で、特別なものではない。

REST API

フロントエンドとバックエンドが会話するための「共通の言葉・窓口」。たとえば 「/api/filesにこのノートのパスを添えて聞くと、その中身を返してくれる」というような、 決まった形の質問と答えのやり取り。フロントエンドとバックエンドは別々のプログラム(別々に起動していて、 別々に壊れうる)なので、この窓口(API)を介してしかお互いのことを知らない。この分離のおかげで、 たとえば将来「画面だけ全部作り直す」といったこともバックエンド側に手を入れずにできる。

バックエンド(webobsidian、Node.js)

「vaultの中身を実際に読み書きする係」。フロントエンドからの「このノートちょうだい」「保存して」 というお願いを受けて、実際にMacのディスク上のファイルを開いたり書き換えたりする。 Node.jsはJavaScriptというプログラミング言語をサーバー(裏方)側で動かすための実行環境。 webobsidianは他の人が作って公開している既存のソフトを取り込んで(fork)、自分の使い方に 合わせて一部を書き換えて(パッチして)使っているもの。ゼロから全部自分で作らなくても、 既にある「vaultをWeb越しに読み書きする」という難しい部分を流用できるのが利点。

なぜDockerではなくbare-metal(そのままNodeで実行)なのか: Dockerは「プログラムを箱(コンテナ) に閉じ込めてどの環境でも同じように動かす」ための仕組みだが、このMac(Intel・古めのmacOS)では Docker導入に必要な下準備(管理者権限でのツール更新)がうまくいかず断念した経緯がある。代わりに Node自体を直接起動する、より原始的だが確実な方法を採っている。

なぜlaunchdなのか: launchdはmacOSに標準で入っている「Macが起動したら自動でこのプログラムを 動かして、落ちたら自動で再起動して」という常駐管理の仕組み。Webサーバーのようにずっと動き 続けてほしいプログラムには、こうした「見張り役」が必要で、その役目をmacOS標準のlaunchdに 任せている(Dockerならrestart: unless-stoppedという設定で同じことができるが、今回はDocker自体を 使っていないため)。

vault本体(~/ObsidianStorage)

すべてのノート(日記・メモ・家計簿など)が実際に保存されている場所。中身は特別なデータベースではなく、 普通のテキストファイル(Markdown)がフォルダに並んでいるだけ。この形式を保つ理由は、 「専用アプリが無くても、いつでも普通のObsidian(メモアプリ)やテキストエディタで開ける」 可搬性を最優先しているため。データベースに閉じ込めてしまうと、このアプリが無くなった瞬間に 中身が読めなくなるが、テキストファイルならその心配がない。

以前は変更履歴の管理にgit(プログラムのソースコード管理でよく使われる、変更の巻き戻しができる 仕組み)を使っていたが、日常のメモ書きにはやや大掛かりすぎたため2026年7月に廃止し、後述の Obsidian Syncだけに一本化した。

frontmatterというのは、各ノートの一番上にある---で囲まれた部分(date:やpublic:が書いてある ところ)のことで、「このノートはいつ書いたか」「公開していいか」といった付加情報(メタデータ)を 機械が読み取れる形で書いておく場所。

「お約束」ノート

このアプリ自体の見た目や動作を決めている設定が、プログラムのコードの中ではなく、 vault内の普通のノートとして置かれている、という今回の設計上の工夫。たとえば配色を変えたい時、 プログラムを書き換えて再起動する代わりに、Design System.mdというノートの数値を書き換えるだけで すぐに反映される。「設定もvaultの一部」にすることで、アプリの見た目とメモの中身が同じ仕組みで 管理できるようになっている。

Obsidian Sync

Obsidian(メモアプリ)の公式機能で、複数の端末(このMacとWin機)の間でvaultの中身を自動的に 同じ状態に保ってくれるサービス。gitのような「変更を1つずつ記録していく」仕組みとは違い、 「ファイルが変わったら丸ごと相手に送る」という単純な同期の仕組み。以前はiCloud経由の共有を 使っていたが、今はこちらに移行している。

もう一方の端末(Win機)

Win機は独自にwebobsidianを動かしているわけではなく、あくまでObsidian Syncで同期されたvaultの コピーを持っているだけ。このサイト(HKDG)を見たい時は、Win機のブラウザからTailscale経由で 家のMacのwebobsidianに直接アクセスする(Win機側のvaultコピーを直接読み書きすることはない)。 理由は、もし両方の端末が同時にvaultを直接いじれる状態にすると、同じファイルへの変更が 衝突してしまう可能性があるため。「vaultを直接触れるのはMac側の1箇所だけ」に絞ることで、 この事故を防いでいる。』

Map_DigitalGarden