# HyperDrive 仕様書

HyperDrive（storage プロジェクト）の仕様ドキュメント入口。詳細は各リンク先を参照すること。

---

## 1. プロジェクト概要

**サービス名:** HyperDrive

**コンセプト・解決する問題**

Google Drive の利便性をベースに、**P2P 技術によるプライバシー保護**と **AI による高度なセマンティック検索**を統合した、セルフホスト可能な個人用ナレッジ・管理システム。

主な解決課題:

| 領域 | 解決する問題 |
|------|----------------|
| P2P インシデント共有 | 共有リンクの発行や権限設定の手間を省き、合言葉だけでセキュアな受け渡しを可能にする。機密ファイルはデバイス間で完結し、サーバーに実体やログが残らない |
| ベクトル検索 | 「内容は覚えているがファイル名・保存場所がわからない」問題を、曖昧なワード（例: 「青い空の画像」「去年の会議資料」）で解決する |
| OCR 検索 | スクリーンショットや領収書など、画像内にしかない情報をテキスト検索の対象にする |

**対象ユーザー**

- **一般ユーザー**: 直感的なファイル共有と高度な検索機能を求める層
- **パワーユーザー**: 自分のデータを自分で管理（セルフホスト）し、プライバシーを重視するエンジニア層

**既存サービスとの差別点**

| | Google Drive | Microsoft OneDrive | HyperDrive |
|----|----|----|----|
| データの管理 | 企業 | 企業 | セルフホスト可能 |
| 検索機能 | 高度なラベル探し | 文脈の理解 | 全データをベクトル化 |
| ファイル共有 | サーバー経由 | サーバー経由 | P2P |
| ターゲット | web完結派, スマホユーザー | Windowsユーザー, Officeユーザー | 一般ユーザー、パワーユーザー |

---

## 2. 技術スタック

| カテゴリ | 技術 | 補足 |
|---------|------|------|
| DB | PostgreSQL + SeaORM | 生SQL禁止 → [overview.md](overview.md) |
| Backend | Rust | - |
| Frontend | TanStack Start | - |
| Session | Valkey | - |
| 監視 | Grafana / Prometheus / Loki | - |
| Storage | RustFS | - |
| Python FastAPI | ベクトル化・OCR処理 | multilingual-e5（ベクトル化）、PaddleOCR/EasyOCR（OCR）を実行するサービス |
| Qdrant | ベクトルDB | ファイル内容のベクトル保存・HNSW近傍探索 |
| Plasmo | ブラウザ拡張 | ブラウザ上での画像キャプチャ・OCR送信 |

---

## 3. データベース設計方針

物理削除（Row を消す操作）は行わない。別途フラグを持つことで削除したことにする。

- テーブル定義: [テーブル定義.md](テーブル定義.md)
- マイグレーション手順: [migration.md](migration.md)

---

## 4. APIエンドポイント一覧（早見表）

※ フォルダー系作成・削除のエンドポイントに typo あり (`/v1/forders`)

| カテゴリ | 機能 | メソッド | エンドポイント | 認証要否 | 詳細 |
|---------|------|--------|------------|--------|------|
| アカウント系 | 作成 | POST | /v1/auth/register | 不要 | [アカウント系/作成.md](アカウント系/作成.md) |
| アカウント系 | ログイン | POST | /v1/auth/login | 不要 | [アカウント系/ログイン.md](アカウント系/ログイン.md) |
| アカウント系 | ログアウト | POST | /v1/auth/logout | 要 | [アカウント系/ログアウト.md](アカウント系/ログアウト.md) |
| アカウント系 | 現在ユーザー（実装のみ） | GET | /v1/auth/me | 要 | セッション確認用。仕様早見表の `/v1/accounts/me` とは別パス |
| アカウント系 | 変更 | PATCH | /v1/accounts/:id | 要 | [アカウント系/変更.md](アカウント系/変更.md) |
| アカウント系 | 削除 | DELETE | /v1/accounts/me | 要（管理者権限） | [アカウント系/削除.md](アカウント系/削除.md) |
| アカウント系 | 凍結 | PATCH | /v1/accounts/:id/freeze | 要（管理者権限） | [アカウント系/凍結.md](アカウント系/凍結.md) |
| アカウント系 | 凍結解除 | PATCH | /v1/accounts/:id/unfreeze | 要（管理者権限・凍結状態） | [アカウント系/凍結解除.md](アカウント系/凍結解除.md) |
| アカウント系 | プロフィール取得 | GET | /v1/accounts/me | 要 | [アカウント系/プロフィール取得.md](アカウント系/プロフィール取得.md) |
| アカウント系 | 一覧 | GET | /v1/accounts | 要（管理者権限） | [アカウント系/一覧.md](アカウント系/一覧.md) |
| ファイル系 | アップロード | POST | /v1/files | 要 | [ファイル系/アップロード.md](ファイル系/アップロード.md) |
| ファイル系 | 一覧 | GET | /v1/files | 任意（open共有は不要、secret共有は要） | [ファイル系/一覧.md](ファイル系/一覧.md) |
| ファイル系 | マイファイル一覧 | GET | /v1/files/mine | 要 | [ファイル系/マイファイル一覧.md](ファイル系/マイファイル一覧.md) |
| ファイル系 | 更新 | PATCH | /v1/files/:id | 要 | [ファイル系/更新.md](ファイル系/更新.md) |
| ファイル系 | 削除 | DELETE | /v1/files/:id | 要 | [ファイル系/削除.md](ファイル系/削除.md) |
| ファイル系 | ゴミ箱 | GET | /v1/files/trash | 要 | [ファイル系/ゴミ箱.md](ファイル系/ゴミ箱.md) |
| ファイル系 | ゴミ箱から復元 | POST | /v1/files/trash/:id/restore | 要 | [ファイル系/復元.md](ファイル系/復元.md) |
| ファイル系 | ゴミ箱を空にする | DELETE | /v1/files/trash | 要 | [ファイル系/ゴミ箱空.md](ファイル系/ゴミ箱空.md) |
| ファイル系 | 閲覧 | GET | /v1/files/:id | 任意 | [ファイル系/閲覧(要修正).md](ファイル系/閲覧(要修正).md) |
| ファイル系 | リンク共有 | POST | /v1/files/:id/links | 要（公開フラグ要） | [ファイル系/共有系/リンク共有.md](ファイル系/共有系/リンク共有.md) |
| ファイル系 | 共有リンク一覧 | GET | /v1/files/:id/links | 要 | [ファイル系/共有系/共有リンク一覧.md](ファイル系/共有系/共有リンク一覧.md) |
| ファイル系 | 共有リンク削除 | DELETE | /v1/files/:id/links/:link_id | 要 | [ファイル系/共有系/共有リンク削除.md](ファイル系/共有系/共有リンク削除.md) |
| ファイル系 | 合言葉共有 | POST | /v1/files/watchword | 要（合言葉共有トグル要） | [ファイル系/共有系/合言葉共有.md](ファイル系/共有系/合言葉共有.md) |
| ファイル系 | ダウンロード | GET | /v1/files/:id/download | 要 | [ファイル系/共有系/ダウンロード.md](ファイル系/共有系/ダウンロード.md) |
| フォルダー系 | 作成 | POST | /v1/forders | 要 | [フォルダー系/作成.md](フォルダー系/作成.md) |
| フォルダー系 | 一覧 | GET | /v1/folders | 要 | [フォルダー系/一覧.md](フォルダー系/一覧.md) |
| フォルダー系 | 更新 | PATCH | /v1/folders/:id | 要 | [フォルダー系/更新.md](フォルダー系/更新.md) |
| フォルダー系 | 削除 | DELETE | /v1/forders/:id | 要 | [フォルダー系/削除.md](フォルダー系/削除.md) |
| 検索系 | 内容検索 | GET | /v1/search | 要 | [検索系/内容検索.md](検索系/内容検索.md) |
| 検索系 | ベクトル検索 | GET | /v1/search | 要 | [検索系/ベクトル検索.md](検索系/ベクトル検索.md) |
| 検索系 | ファイル名検索 | GET | /v1/search | 要 | [検索系/ファイル名検索.md](検索系/ファイル名検索.md) |
| 検索系 | アカウント名検索 | GET | /v1/search | 要（管理者権限） | [検索系/アカウント名検索.md](検索系/アカウント名検索.md) |
| 検索系 | OCR検索 | GET | /v1/search | 要 | [検索系/OCR検索.md](検索系/OCR検索.md) |
| P2P | シグナリング | WS | /v1/ws/watchword | 要 | [インフラ/WebSocketシグナリングエンドポイント.md](インフラ/WebSocketシグナリングエンドポイント.md) |

---

## 5. その他ドキュメント

### 5.1 凍結アカウントの挙動

[凍結時の挙動.md](凍結時の挙動.md)

### 5.2 UIコンポーネント一覧

[コンポーネント.md](コンポーネント.md)

### 5.3 コーディング規則

[コーディング規則.md](コーディング規則.md)

### 5.4 開発環境セットアップ

[開発環境.md](開発環境.md)

### 5.5 インフラ・外部サービス仕様

- [TURNサーバー](インフラ/TURNサーバー.md)
- [WebRTCシグナリング](インフラ/WebRTCシグナリング.md)
- [ベクトル検索基盤](インフラ/ベクトル検索基盤.md)
- [OCRエンジン](インフラ/OCRエンジン.md)

### 5.6 共通仕様

- [エラーレスポンス](共通/エラーレスポンス.md)
- [ページネーション](共通/ページネーション.md)
- [権限モデル](共通/権限モデル.md)

### 5.7 その他インフラ

- [メールサービス](インフラ/メールサービス.md)
- [WebSocketシグナリングエンドポイント](インフラ/WebSocketシグナリングエンドポイント.md)

### 5.8 実装ガイド（開発者向け）

- [DBスキーマ](実装ガイド/DBスキーマ.md)
- [サービスアーキテクチャ](実装ガイド/アーキテクチャ.md)
- [実装順序](実装ガイド/実装順序.md)
- [環境変数](実装ガイド/環境変数.md)

### 5.9 P2Pファイル転送（詳細）

- [P2Pファイル転送（詳細）](インフラ/P2Pファイル転送.md)