COMPASS Platform
Don’t Just Learn. Build What’s Next.
学びを、意思決定の力へ。
公開Web · 開発に参加する · アーキテクチャ · 文書索引 · 利用許可
COMPASS Platformは、主に北里大学の学生に向けて、学習・進路・コミュニティを横断したデジタル体験を提供する、学生主導型の教育・テクノロジープラットフォームである。北里大学および同大学の学部・研究室・関連機関の公式組織・公式サービスではない。
このリポジトリは、3D空間を取り入れた公式Webサイト、Contact・Communityの公開フォーム、未来戦略ライブラリの登録基盤（API・データベース・インフラ）と、その開発・検証の仕組みを管理する。COMPASS Interactiveのアプリケーション本体は、別のリポジトリ・別の環境で開発している。
開発に参加する方へ
開発に参加するときは次の3つを順に読み、作業のたびに関係する節を確認すること。AI agentも同じ文書に従う。
- チーム開発ルール：役割、変更の区分、branch、review、merge、本番公開
- CONTRIBUTING：開発環境の用意から最初のPRまで
- AGENTS.md：作業範囲、編集・検証・承認の規則
そのほかの文書は文書索引にまとめている。
アーキテクチャ
公開ページは静的に配信し、利用者の入力を受ける処理だけをCloudflare Pages Functionsと登録基盤のAPIに分ける。
flowchart LR
Browser["ブラウザ"] --> Pages["Cloudflare Pages / 静的Web"]
Browser --> Edge["Pages Functions / Turnstile"]
Edge --> GAS["Google Apps Script / 公開フォーム通知"]
Browser --> Public["Library Public API"]
Browser --> Access["Cloudflare Access / 管理API Proxy"]
Access --> Admin["Library Admin API"]
Public --> DB[("PostgreSQL / 状態・権限・Outbox")]
Admin --> DB
Scheduler["Cloud Scheduler"] --> Worker["Drive Worker"]
Worker --> DB
Worker --> Drive["Google Drive"]
各サービスの役割はArchitectureにある。
実行環境
| 環境 | 実行場所 | 構成 | 状態 |
|---|
| 公式Web | Cloudflare Pages（compass-official） | Next.jsのstatic export。mainへのmergeがProduction配信を起動し得る | Production |
| 公開フォーム（Contact・Community） | Cloudflare Pages Functions → Google Apps Script | Turnstileと入力検証の後、GASが通知メールを送る。問い合わせ本文と登録内容をデータベースに保存しない | ページはProductionで配信中。Turnstile・GAS・Secretの外部設定は各runbookでoperatorが確認する |
| 未来戦略ライブラリ登録基盤 | Google Cloud Run · Neon PostgreSQL | Public API、Admin API、Drive Worker、Migration Jobを分離 | Implemented, verification pending。本登録のroute・APIは未公開（Phase Roadmap） |
| COMPASS Interactive本体 | 別のリポジトリ・別の環境 | — | このリポジトリの対象外 |
Interactive紹介などの独立した編集範囲も同じNext.jsの成果物から配信するが、COMPASS公式サイトとは編集の範囲を分けている（Website Boundaries）。
ディレクトリ構成
公式トップは src/app/(official)/page.tsx → src/App.tsx → src/LegacyPageBody.tsx の順に描画される。LegacyPageBody.tsx は名称に反して現行の実装である。
ブラウザで描く3D空間
公式トップのHabitatは、Three.jsのWebGL描画とHTMLのUIで構成する。9つのセクションに対応する空間とカメラを、1つのレンダラーで連続して描く。
- 文章、リンク、見出し、フォームは既存のcomponentが通常のDOMとして持ち、3Dはその背後の空間として描く。3Dが動かない環境でも、内容と遷移先は変わらない。
- 3Dは、画面幅901px以上で精密なポインターを持つ端末と、901px以上の横向きタブレットで有効にする。縦向きのタブレットとスマートフォンは静的なレイアウトを使う。端末の種類で画質を下げないため、条件を満たす端末では同じシーンを描く。
- Reduced Motionでは各セクションの静止画を使い、3Dエンジンとモデルを読み込まない。GLBの読み込み失敗、WebGLの欠如、コンテキストの喪失、3秒間の計測が2回続けて28fpsを下回った場合も、静止画とHTMLに切り替える。
- 建築と家具はBlenderで制作し、間接光をライトマップに焼き込む。ランタイムではPBR材質、HDR環境光、反射、Bloomを使い、glTF/GLBはMeshopt、画像はWebPで圧縮する。
- 音は利用者の操作の後にだけ、ブラウザ内で合成して鳴らす。自動再生、マイク、音声ファイルの取得はない。非表示のタブでは消音する。
実装はHabitat、設計はParent Desktop habitat、制作手順はAuthoring Guide、素材の出典はAsset Creditsにある。通常のWebビルドにBlenderは要らない。
モバイルと映像
- 縦向きのタブレットとスマートフォンでは、NASAが撮影・公開した国際宇宙ステーションからの写真とタイムラプスを使う。AIによる生成、補間、架空の天体は使わない。
- 動画は表示領域と通信状態に応じて読み込みと再生を制御し、データ節約設定、低速回線、再生の失敗では静止画に切り替える。モバイルでは3DエンジンとGLBを読み込まないことをテストで確かめている。
- Contactの入口では、Blenderで制作した建物の映像の扉にHTMLのボタンを重ね、選んだ部屋へ映像で移る。映像は選択の後にだけ読み込む。演出は飛ばせて、Reduced Motionや読み込みの失敗でも同じフォームに着く。
詳細はMobile Space MediaとContact Door Entryにある。
公開フォーム
ContactとCommunityの参加申請は、Next.jsの静的ページとCloudflare Pages Functionsで受け付け、Google Apps Scriptが通知メールを送る。
- 送信はTurnstileとサーバー側の入力検証を通った場合だけGASへ渡す。
- ContactとCommunityは、endpoint、入力のschema、Turnstileのkeyとaction、GASのプロジェクト、共有シークレット、メールの流れを分け、明示的なarchitectureの変更なしに統合しない（Architectureの「Form Isolation」）。
- どちらもデータベースを使わない。Contactでは、GASが一時的に持つのは10分間のメール確認の状態、レート制限、送信の冪等性の情報だけで、確認コード、メールアドレス、IPアドレスは平文で保存せず、必要な識別値だけをHMAC化する。
設定と運用の手順はContact Form OperationsとCommunity Registration Operationsにある。
未来戦略ライブラリ登録基盤
状態はImplemented, verification pendingである。設計と実装はローカルと合成データで検証済みで、本登録のroute・APIの公開、billing、Terraform applyは未実施である。判定の正本はPhase Roadmapにある。
FastAPI、Neon PostgreSQL、Google Cloud Runを中心に構成し、Public API、Admin API、Drive Worker、Migration Jobを分けて、それぞれに必要な権限だけを持たせる。
| 仕組み | 防ぐこと |
|---|
| Google Driveへの権限の反映を、Transactional OutboxでWorkerへ渡す | データベースの更新とDriveの権限の食い違い |
| WorkerはCloud SchedulerからOIDC付きで起動し、Lease・Retry・操作署名を確かめてから実行する | 二重実行と、途中で失敗した処理の取り残し |
| サービスごとにデータベースのロールを分け、権限の境界をまたぐ処理はRPCに寄せる | 権限外の表の操作 |
| Google IDトークンと管理者権限をサーバー側で判定する | 画面の表示だけに頼った認可 |
| 管理APIはCloudflare Access、共有シークレット、データベースの権限を重ねる | 1つの防御を破られただけで行える管理操作 |
| Secret Managerで接続情報を用途ごとに分け、各サービスには必要なSecretだけを渡す | 1つのサービスからの全認証情報の漏えい |
| 管理操作、権限の変更、エクスポートを監査ログに記録する | 誰が何を変えたか追えないこと |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
