OpenShelf

OpenShelf は、研究成果物（論文、プレゼン資料、データセット等）を安全にアップロードし、共有するためのファイルホスティングプラットフォームです。

利用者は GitHub アカウントを用いて安全にログインし、成果物を素早く公開・共有できます。Cloudflare Workers (Hono) と Next.js を組み合わせたモダンな構成で、スケーラビリティとセキュリティを両立しています。

📋 主な機能・利用メリット

• 📄 ファイルホスティング: Cloudflare R2 を活用した安全で低コストなファイル保存。
• 🔗 共有リンク生成: アップロード後、即座に共有用の URL を発行。
• 👥 コラボレーション: 招待制アクセスによるチーム内共有と、共著者（Co-author）管理機能。
• 🔐 セキュアな認証: GitHub OAuth 2.0 と JWT を使用。
• 🚀 複数デプロイ対応: クラウド（Vercel/Cloudflare）またはオンプレミス（Docker）にデプロイ可能。

---

🏗️ サービス構成 (Architecture)

OpenShelf は npm workspaces を使ったモノレポ構成です。

apps/
├── web/   ← Web フロントエンド (Next.js)
│           ├─ App Router 採用
│           └─ Docker / Vercel 両対応
│
└── api/   ← API バックエンド (Hono / Workers)
            ├─ D1 (DB) / R2 (Storage)
            └─ GitHub OAuth 認証

技術スタック:

Phase	Tech
Frontend	Next.js 16+, React 19, TypeScript 5, Tailwind CSS 4
Backend	Hono 4, Cloudflare Workers
Database	SQLite (D1) / Drizzle ORM
Storage	Cloudflare R2
Auth	GitHub OAuth 2.0, JWT
Testing	Vitest, Playwright (E2E)

---

使い方 (ユーザー向け)

1. ログイン・新規登録

• トップ画面の「Sign in with GitHub」ボタンからログインします。
• 注意: OpenShelf は招待制です。初めて利用する場合は、すでに利用しているメンバーから招待リンク (Invite Link) を受け取ってください。

2. ファイルのアップロード

• ログイン後、「Upload」画面から成果物となるファイルを登録します。
• タイトル、アブストラクト、公開範囲（Public, Org-Only, Private）などのメタデータを設定できます。

3. ファイルの共有・共著者招待

• アップロード完了後、詳細ページから共有 URL をコピーできます。
• 「Co-author Invite」機能を使うことで、他のユーザーを共著者として追加し、編集権限を共有できます。

---

開発者・システム管理者向け (Setup & Deployment)

ローカルセットアップ (Local Setup)

1. リポジトリのクローンとインストール

   git clone https://github.com/Hiroki-org/OpenShelf.git
   cd OpenShelf
   npm install

2. GitHub OAuth App の作成

   • GitHub Developer Settings で新規アプリを作成。
   • Homepage URL: http://localhost:3000
   • Authorization callback URL: http://localhost:3000/auth/callback

3. 環境変数の設定

   API (apps/api/.dev.vars):

   GITHUB_CLIENT_ID=<your-client-id>
   GITHUB_CLIENT_SECRET=<your-client-secret>
   JWT_SECRET=dev-secret-change-in-prod
   FRONTEND_URL=http://localhost:3000

   Web (apps/web/.env.local):

   API_URL=http://localhost:8787
   NEXT_PUBLIC_API_URL=http://localhost:8787

4. 起動

   # API: cd apps/api && npm run dev
   # Web: cd apps/web && npm run dev

---

デプロイ (Deployment)

Vercel Deployment (Web)

1. Vercel に apps/web を Root Directory としてインポート。

2. Environment Variables に以下を設定:

   • NEXT_PUBLIC_API_URL: デプロイ済みの Cloudflare Worker URL（ブラウザ側 OAuth 開始・API 呼び出しで使用）
   • API_URL: デプロイ済みの Cloudflare Worker URL
   • FRONTEND_URL: 自身の URL (例: https://openshelf.vercel.app)

   CLI での設定例:

   vercel env add FRONTEND_URL production

Cloudflare Workers Deployment (API)

OpenShelf API は staging / production の 2 環境で運用します。

• apps/api/wrangler.toml では [env.staging] と [env.production] を定義しています。
• トップレベルに D1 / R2 の binding は置いていません。wrangler dev、wrangler deploy、wrangler d1 migrations apply などの環境依存コマンドは、必ず --env staging または --env production を指定してください。
• デプロイは GitHub Actions 経由で行います。apps/api/** の変更を含む push のみが対象です。
  • staging ブランチへの push かつ apps/api/** 変更あり → staging 環境へ自動デプロイ
  • main ブランチへの push かつ apps/api/** 変更あり → production 環境へ自動デプロイ
  • 例: main に apps/api/** 以外の変更だけを push しても、Deploy API ワークフローは起動しません。
• デプロイ時には wrangler d1 migrations apply が各環境に対して自動実行されます。

開発フロー

通常の開発フロー（staging 先行）:

1. main から feature branch を作成
2. 実装・ローカルテスト
3. staging 宛てに PR を作成（CI が自動実行）
4. レビュー・マージ → staging に自動デプロイ
5. staging 環境で動作確認
6. 問題なければ npm run pr:promote で staging → main の PR を作成または更新
7. マージ → production に自動デプロイ

Note

main 宛てに PR を作成した場合、source が staging でなければ staging に自動で retarget されます（pull_request_target の opened / reopened / edited で適用）。 main への push 後は、main → staging の同期 PR を自動で作成または再利用します。 staging の検証後は npm run pr:promote を実行すると、staging → main の promotion PR を作成または更新し、description に含まれる PR 一覧も自動生成します。事前確認だけ行いたい場合は DRY_RUN=1 npm run pr:promote を使ってください。

緊急 hotfix:

1. main から hotfix branch を作成
2. staging 宛てに PR を作成して staging で動作確認
3. 問題なければ staging → main の PR を作成
4. マージ → production に自動デプロイ

Note

rollback / E2E テスト戦略の詳細化は今後整理します。

D1 マイグレーション運用

• マイグレーションファイルは apps/api/drizzle/ に配置します。
• 適用済みマイグレーションはイミュータブルです。既存ファイルは変更せず、新しい番号のファイルを追加してください。
• スキーマ変更があるたびに、新しい番号のマイグレーションファイルを追加します。
• デプロイ時に wrangler d1 migrations apply が staging / production それぞれに対して自動実行されます。
• ローカルでは npm run db:migrate:local、リモートでは npm run db:migrate:remote:production を使います。
• 既存マイグレーションファイルの変更は CI で検知されます。

Secrets 管理

• GitHub Actions Secrets
  • CLOUDFLARE_API_TOKEN
  • CLOUDFLARE_ACCOUNT_ID
• Workers Secrets (npx wrangler secret put で環境ごとに設定)
  • GITHUB_CLIENT_ID
  • GITHUB_CLIENT_SECRET
  • JWT_SECRET
• apps/api/wrangler.toml の環境別 [vars]
  • env.production.vars: FRONTEND_URL, ALLOWED_ORIGINS, NODE_ENV
  • env.staging.vars: FRONTEND_URL, ALLOWED_ORIGINS, NODE_ENV

Docker (Self-Host / VPS)

詳細は apps/web/README.md#self-host-docker を参照してください。

---

🧪 テスト・品質管理

npm run test           # API単体テスト
npm run typecheck      # 型チェック
npm run lint           # リンター実行
# E2Eテスト (apps/e2e)
cd apps/e2e && npx playwright test

---

🤖 エージェント向けドキュメント

• AGENTS.md — どのエージェントでも最初に読む共通入口
• docs/agent-tooling.md — OpenShelf における Dosu / Notion / ntn の正本ドキュメント（CLI / MCP / 知識保存）
• .github/copilot-instructions.md — OpenShelf 固有の開発ルール

---

📄 ライセンス

MIT License