● Spy Control Center Guide
プロジェクト解説ガイド

Spy Control Center ってどういうアプリ?
コードの中身を一緒に見ていきます

「スパイ体験型アトラクション」の運営スタッフが使う、カメラ映像・センサー状態・イベントログを 1画面で確認する管理コンソールです。このページでは、プログラミング初学者ではないけれど Web技術にはまだ詳しくない方向けに、技術的な仕組みとコードの構成をやさしく解説します。

全体構成 — 3つのパーツでできている

このアプリは大きく3つの部分に分かれています。それぞれ別の役割を持ち、別の場所で動いています。

① ブラウザのアプリ本体 SvelteKit + Svelte 5
Cloudflare Pages配信
↔
② 状態共有サーバー Cloudflare Workers
Durable Objects
↔
③ カメラ映像サーバー(任意) go2rtc
運営スタッフのPC上で動作

① アプリ本体

ブラウザで見ている画面そのもの。ダッシュボード、カメラ一覧、センサー一覧などの画面を描画します。 Cloudflare Pagesという「静的サイトを世界中に配信してくれるサービス」に置かれていて、 誰がどこからアクセスしても同じページが届きます。

② 状態共有サーバー

「カメラが今オンラインかどうか」「センサーが反応したか」「イベントログに何が記録されたか」といった “みんなで共有すべきデータ”を1か所で管理するサーバーです。複数の端末(PC・スマホなど)で同時に開いても、 同じ状態が全員に届くようにする役目を持ちます。

③ カメラ映像サーバー(go2rtc)

実機カメラ(Tapo C100など)の映像は、カメラが話す「RTSP」という古い方式のままではブラウザで再生できません。 go2rtcというソフトが、運営スタッフのPC上でRTSP映像をブラウザが再生できる形式に変換してくれます。 これは各拠点ごとに個別に用意する想定の、ローカルな仕組みです。

先に知っておくと読みやすい用語

コード解説の前に、このプロジェクトで頻出する言葉をざっと説明します。

SvelteKit / Svelte

「画面の見た目と動き」を作るためのWebフレームワーク。Reactなどの仲間です。 画面の部品(ボタン、カード、一覧表など)を.svelteファイルという単位で 組み立てていきます。

TypeScript

JavaScriptに「このデータはどんな形をしているべきか」という型の情報を追加した言語。 「カメラの状態は ONLINE/OFFLINE/CONNECTING/ERROR の4種類のどれかしかありえない」といった 決まりをコードに書けるので、typoやうっかりミスに気づきやすくなります。

WebSocket

ブラウザとサーバーの間を「ずっとつないだまま」お互いにメッセージを送り合える通信方式。 通常のWebページの読み込み(1回だけ送って1回だけ返事をもらう)と違い、 サーバー側から「センサーが反応しました」とリアルタイムに知らせることができます。

Cloudflare Workers / Durable Objects

Workersは「サーバーのプログラムを世界中の拠点で動かしてくれるサービス」。 Durable Objectsはその上で、「1つの状態(今回はカメラやセンサーの状態)を、 常に1か所で一貫して保持してくれる」仕組みです。複数人が同時にアクセスしても データが競合しないようにしてくれます。

RTSP

監視カメラなどの映像機器が昔からよく使う映像配信の規格。 ブラウザは直接これを再生できないため、別の形式に変換するサーバー(go2rtc)が必要になります。

localStorage

ブラウザがページごとに持っている「小さな保存領域」。サーバーを介さずに、 端末の設定(アプリ名、通知のON/OFFなど)をブラウザの中だけに保存しておく時に使います。

操作してから画面が変わるまでの流れ

例として「あるスタッフがセンサーの『反応させる』ボタンを押した」場合に、 裏側で何が起きて、他の端末の画面にも反映されるのかを順番に見てみます。

1

ボタンを押す

画面のボタンが systemState.triggerSensor(id) を呼び出します。これはアプリ内の「状態管理」役のオブジェクトです。

2

サーバーにメッセージを送る

自分の端末ではデータを直接書き換えず、「センサーを反応させて」というメッセージをWebSocket経由で状態共有サーバー(Durable Object)に送ります。

3

サーバー側で状態を更新

サーバーがそのセンサーの状態を書き換え、イベントログに1件追加し、保存します(tools/realtime-worker/src/room.ts)。

4

全端末に新しい状態を配信

更新後の状態全体を、今つながっている全ての端末にWebSocketで一斉に送り返します(ブロードキャスト)。

5

各端末の画面が自動で更新される

受け取った端末側では、受信した状態をそのまま画面の表示用データに反映するので、ボタンを押した人以外の画面も自動的に切り替わります。

💡 ポイント: このアプリは「自分の画面だけ書き換えて、あとでサーバーと合わせる」方式ではなく、 「必ずサーバー経由で書き換えて、サーバーからの返事を信じる」方式を採っています。 これにより複数端末間でデータがズレる心配がありません。

コード一覧と解説

プロジェクトの主なフォルダ・ファイルを、役割別にまとめました。カードをクリックすると詳しい解説が開きます。

# フォルダ構成(抜粋)
src/
├── routes/              # 画面(URLのパスに対応)
│   ├── +page.svelte       # "/"  ダッシュボード
│   ├── cameras/+page.svelte
│   ├── camera-rotation/+page.svelte
│   ├── sensors/+page.svelte
│   ├── events/+page.svelte
│   └── settings/+page.svelte
│
└── lib/
    ├── components/       # 画面を組み立てるパーツ
    │   ├── cameras/, sensors/, events/, dashboard/, layout/
    ├── stores/            # 状態管理(データの一元管理)
    │   ├── system-state.svelte.ts
    │   └── simulation.svelte.ts
    ├── utils/             # 通信や細かい処理
    │   ├── realtime-client.ts
    │   ├── qr-scanner.ts
    │   ├── storage.ts
    │   └── csv-export.ts
    ├── types/index.ts    # 型定義(データの"形"のルール)
    └── data/mock-data.ts # 初期データ(モック)

tools/realtime-worker/    # ② 状態共有サーバー(別デプロイ単位)
├── src/index.ts, room.ts, types.ts, initial-data.ts

tools/go2rtc/              # ③ カメラ映像サーバーの設定・起動スクリプト
src/lib/types/index.ts 型定義 ▸

アプリ全体で使う「データの形」を定義するファイルです。たとえばカメラのデータは必ず次の形を持つ、と決めています。

interface Camera {
  id: string;
  name: string;
  status: 'ONLINE' | 'OFFLINE' | 'CONNECTING' | 'ERROR';
  connectionType: 'RTSP_MOCK' | 'RTSP_LIVE';
  // ...
}

このように型を決めておくことで、「statusに存在しない文字列を入れてしまう」ような ミスをコードを書いている最中に検出できます。また、サーバーとブラウザの間でやり取りするメッセージの種類 (ClientMessage / ServerMessage) もここで定義されており、 「ありうる通信の種類」が一覧になっています。

src/lib/stores/system-state.svelte.ts 状態管理 ▸

アプリの「今の状態」をまとめて持っているファイルです。カメラ一覧・センサー一覧・イベントログなどを SystemStateというクラスのプロパティとして保持し、画面側はここから値を読んで表示します。

  • $state(...) はSvelte 5の書き方で、「このデータが変わったら、使っている画面を自動的に再描画して」という目印です。
  • カメラやセンサーを操作する関数(triggerSensorなど)は、データを直接書き換えず、状態共有サーバーへメッセージを送るだけになっています。実際の書き換えはサーバーからの返事を受け取ったときに行われます。
  • 一方で「アプリ名」「通知ON/OFF」などの端末ごとの好み設定は、サーバーと共有せずlocalStorageにだけ保存します(他の端末の表示設定に影響を与えないようにするため)。
src/lib/utils/realtime-client.ts 通信 ▸

ブラウザ側で、状態共有サーバー(Cloudflare Workers上のDurable Object)とのWebSocket通信を担当するファイルです。

  • ページを開くと自動的にサーバーへ接続します。
  • 接続が切れた場合は2秒後に自動的に再接続を試みます(Wi-Fiが不安定な環境でも粘り強くつながり続けるようにする工夫です)。
  • 接続できていない間に操作をしても、メッセージはその場で捨てられます。再接続後にサーバーから最新の状態をまとめて受け取るため、古い操作が後から誤って適用される心配がありません。
src/lib/utils/qr-scanner.ts カメラ映像解析 ▸

実機カメラの映像から、QRコードをブラウザの中だけで検出する機能です(jsQRという ライブラリを利用)。映像フレームをキャンバス(見えない描画領域)に一度描いて、その画像データを解析します。

  • 約0.4秒ごとに1回、映像の1コマをチェックします。
  • 解析はすべて端末内(ブラウザ)で完結し、外部サービスへ映像やデータを送信しません。
  • 特定のQRコード(ALERT-001)を検出すると、「警告QRを検知した」という特別な通知がサーバー経由で全端末に配信されます。
  • 同じQRコードが写り続けている間は、10秒間は重複通知を抑制し、イベントログが同じ内容で埋め尽くされないようにしています。
src/lib/components/cameras/LiveVideoPlayer.svelte 画面パーツ ▸

実機カメラ映像(connectionType: 'RTSP_LIVE')を表示するための動画プレイヤー部品です。 go2rtcサーバーとWebSocketで接続し、映像データ(WebRTC/MSE形式)を受け取って<video>要素に流し込みます。 go2rtcに接続できない場合は、自動的に「NO SIGNAL」表示に切り替わるようになっています。

src/lib/data/mock-data.ts 初期データ ▸

アプリを初めて開いたときに表示される「サンプルデータ」をまとめたファイルです。 カメラ3台(Entrance / Corridor / Laser Room)、センサー数台、初期イベントログなどが あらかじめ定義されています。実機のカメラやセンサーが未接続の状態でも、 画面の見た目や操作感を確認できるようにするためのものです。

tools/realtime-worker/src/room.ts サーバー(Workers) ▸

②の「状態共有サーバー」の本体です。CloudflareのDurable Objectという仕組みを使って、 カメラ・センサー・イベントログの「正しい最新状態」を1か所で管理します。

  • クライアント(ブラウザ)から届いたメッセージ(例: 「カメラを追加して」)を受け取り、状態を書き換えます。
  • 書き換えた直後に、今つながっている全クライアントへ最新の状態を送り返します(ブロードキャスト)。
  • 「WebSocket Hibernation API」という仕組みを使っており、しばらく誰も操作しなければサーバー側のプログラムは一旦スリープします。これにより、ずっと誰かが使っていなくても課金が最小限に抑えられる設計になっています。
tools/go2rtc/(go2rtc.yaml ほか) カメラ連携 ▸

実機カメラ(Tapo C100など)の映像をブラウザで見られるようにするための、go2rtcというソフトの設定・起動スクリプト一式です。

  • go2rtc.yaml にカメラのRTSP接続先(IPアドレス・ユーザー名・パスワード)を記入します。この設定ファイルはパスワードを含むため、Gitの管理対象外(.gitignore)になっています。
  • go2rtcはアプリ本体とは別に、カメラがある拠点の近くのPCで動かす想定です。
  • HTTPSで配信されている本番アプリから接続するには、go2rtc側も暗号化通信(TLS / wss://)に対応させる必要があります(ブラウザは暗号化されたページから非暗号化の接続を自動的にブロックするため)。

どこで動いているか

パーツデプロイ先状態
アプリ本体 spy-control-center.pages.dev 公開中
状態共有サーバー Cloudflare Workers(Durable Objects) 公開中
カメラ映像サーバー(go2rtc) 運営スタッフのPC(ローカル/LAN限定) 任意・運用時のみ起動

🚀 本番アプリを開いてみる