# HyperDrive

**セルフホスト可能な個人用ファイル管理 — P2P 共有と AI 検索をひとつに。**

HyperDrive は、クラウドストレージの使いやすさを保ちながら、データの所在と共有経路を自分でコントロールできるシステムです。ファイルは自分のサーバー上で管理し、機密の受け渡しはデバイス間の直接転送で完結させます。あわせて、ファイル名を思い出せなくても内容から探せるベクトル検索と、画像内テキストを対象にした OCR 検索を備えています。

> **30 秒で把握する要点**
>
> | 何をするか | 自分のサーバーでファイルを保管・整理・検索する |
> | 誰向けか | 一般ユーザー〜プライバシー重視のパワーユーザー |
> | 他と違う点 | 合言葉 P2P 共有・AI 検索・完全セルフホスト |
> | 次に読む | [仕様書](仕様書/仕様書.md) / [実装ガイド](仕様書/実装ガイド/アーキテクチャ.md) |

---

## プロジェクト概要

### サービス名

**HyperDrive**（リポジトリ名: `storage`）

### コンセプト

Google Drive 系サービスが提供する「どこからでもアクセスできるファイル管理」の体験をベースに、次の 2 軸を追加した **個人用ナレッジ・ファイル基盤** です。

1. **プライバシー優先の共有** — 合言葉を知る相手とのみ、WebRTC によるデバイス間直接転送。ファイル実体は中継サーバーに残りません。
2. **意味で探す検索** — アップロードされた文書・画像をベクトル化し、「青い空の写真」「去年の会議メモ」のような曖昧な表現でも候補を絞り込めます。

### 対象ユーザー

| ペルソナ | ニーズ |
|----------|--------|
| **一般ユーザー** | 直感的な UI でファイルを整理し、リンクや合言葉で安全に渡したい |
| **パワーユーザー** | API・セルフホスト・監視スタックまで含め、環境を自分で構築・運用したい |
| **プライバシー重視のエンジニア** | データ所在地を自分で決め、共有ログやクラウド実体の残存を最小化したい |

### 既存クラウドとの位置づけ

| 観点 | 一般的なクラウド | HyperDrive |
|------|------------------|------------|
| データの保管場所 | 事業者のインフラ | 自分が立てたサーバー（セルフホスト） |
| 機密ファイルの受け渡し | サーバー経由のアップロード | P2P（合言葉 + WebRTC） |
| 「名前が思い出せない」検索 | ファイル名・フォルダ中心 | ベクトル検索 + OCR |
| 運用の自由度 | サービス提供範囲内 | ソース・スタックを自分で選択可能 |

---

## 主な特徴

### P2P ファイル共有

合言葉（ウォッチワード）だけで送受信者をマッチングし、**WebRTC DataChannel** 上でファイルを直接転送します。SDP や ICE 候補の交換は HyperDrive の WebSocket シグナリングを経由しますが、**ファイルのバイナリはサーバーに保存されません**。同一 LAN 内だけでなく、STUN/TURN を用いたインターネット越しの接続にも対応する設計です。

### ベクトル検索

アップロードされたテキストや文書を **multilingual-e5** 等でベクトル化し、**Qdrant** に格納します。キーワードの完全一致に頼らず、意味的に近いファイルをランキングして返すため、「内容は覚えているがファイル名がわからない」状況に強いです。

### OCR 検索

スクリーンショット・スキャン画像・写真内の文字列を **PaddleOCR / EasyOCR** で抽出し、通常の全文検索と同様にインデックス化します。ブラウザ拡張（Plasmo）からキャプチャした画像も OCR パイプラインに載せられる想定です。

### セルフホスト

Docker Compose 等で **PostgreSQL・Valkey・RustFS・Qdrant** を含む一式を自分のマシンや VPS に展開できます。認証・セッション・オブジェクトストレージ・ベクトル DB まで、データの境界を自分で定義できます。

### その他の設計上の特徴（概要）

- **論理削除** — 物理削除ではなくフラグで無効化し、監査・復元の余地を残す方針
- **権限モデル** — 一般ユーザーと管理者（凍結・一覧など）を分離
- **監視** — Grafana / Prometheus / Loki による運用可視化（本番想定）

---

## 技術スタック

主要コンポーネントのみ抜粋しています。ポートや通信経路の詳細は [アーキテクチャ](仕様書/実装ガイド/アーキテクチャ.md) を参照してください。

| レイヤ | 技術 | 役割 |
|--------|------|------|
| **DB** | PostgreSQL + SeaORM | アカウント・ファイルメタ・権限などの永続データ（生 SQL 禁止方針） |
| **Backend** | Rust (Axum) | REST API、認証、ファイル管理、WebSocket シグナリング |
| **Frontend** | TanStack Start | Web UI（デフォルトポート 3000） |
| **Session / Cache** | Valkey | セッション、キャッシュ、P2P ルーム状態 |
| **Storage** | RustFS | S3 互換オブジェクトストレージ（ファイル実体） |
| **Vector DB** | Qdrant | ベクトルインデックス・近傍探索（HNSW） |
| **AI Services** | Python FastAPI | OCR・ベクトル化ワーカー（ポート 8000） |
| **Browser Extension** | Plasmo | ブラウザ上での画像キャプチャと OCR 連携 |
| **監視**（任意） | Grafana / Prometheus / Loki | メトリクス・ログの可視化 |

### データの流れ（概要）

```
ブラウザ → TanStack Start → Rust API → PostgreSQL / Valkey / RustFS
                                ↓
                        Python FastAPI → Qdrant
```

P2P 転送時のみ: `ブラウザ ←WebRTC→ ブラウザ`（ファイル本体は API サーバーを通過しない）

---

## ドキュメント構成

このサイト（Retype）は `docs/` 以下をビルドし、**本ページがトップ** です。目的に応じて次のドキュメントへ進んでください。

| ドキュメント | 内容 | リンク |
|--------------|------|--------|
| **仕様書** | API 一覧、DB 方針、各機能の入出力・エラー・権限 | [仕様書/仕様書.md](仕様書/仕様書.md) |
| **実装ガイド（アーキテクチャ）** | サービス一覧、ポート、接続図、開発者向けの全体像 | [仕様書/実装ガイド/アーキテクチャ.md](仕様書/実装ガイド/アーキテクチャ.md) |
| **DB スキーマ** | ER 図に沿ったテーブル・リレーションの説明 | [仕様書/実装ガイド/DBスキーマ.md](仕様書/実装ガイド/DBスキーマ.md) |
| **開発環境** | ローカル起動・依存関係 | [仕様書/開発環境.md](仕様書/開発環境.md) |
| **インフラ** | P2P、TURN、OCR、メール等の横断仕様 | [仕様書/インフラ/](仕様書/インフラ/) 配下各ファイル |

### 仕様書の章立て（早見）

- **アカウント系** — 登録・ログイン・凍結・プロフィール
- **ファイル系** — アップロード、ゴミ箱、リンク共有、合言葉共有
- **検索系** — 内容・ベクトル・ファイル名・OCR
- **フォルダー系** — 階層整理（API パスは仕様書内の早見表を参照）

---

## クイックスタート（開発者向け）

1. リポジトリをクローンし、`docs/仕様書/開発環境.md` の手順で依存サービスを起動する。
2. フロント（TanStack Start）と API（Axum）を立ち上げ、ブラウザで UI にアクセスする。
3. 検索・OCR・P2P を試す場合は、Qdrant・Python FastAPI・TURN 設定が有効であることを確認する。

詳細な環境変数と起動順序は **実装ガイド** に集約されています。

---

## 用語集（最小）

| 用語 | 説明 |
|------|------|
| **合言葉共有** | ウォッチワードで送受信者を結び、P2P 転送を開始する機能 |
| **ベクトル検索** | 文書・テキストの意味類似度に基づく検索 |
| **RustFS** | ファイル実体を置く S3 互換ストレージ層 |
| **Valkey** | Redis 互換のセッション・キャッシュストア |

---

## ライセンス・貢献

プロジェクトのライセンスおよびコントリビューション手順は、リポジトリルートの README および各パッケージの設定を参照してください。ドキュメントの修正は `docs/` 以下の Markdown を編集し、Retype でプレビューできます。

---

*最終更新: ドキュメントサイトのトップページとして整備。詳細仕様は常に [仕様書](仕様書/仕様書.md) を正とする。*