Technical Books Search

Technical Books Search は、Recursionのカリキュラムに関連するキーワードをもとに、Google Books API を使った技術書検索と「積読（tsundoku）」管理をひとつのアプリケーションで提供するフルスタックプロジェクトです。バックエンドは Go、フロントエンドは React + Vite で構成されており、検索→積読追加→読書進捗の管理までをブラウザで完結できます。

主な機能

• 自由キーワード＋ジャンルタグで 技術書 を検索
• 同じ書籍は積読中・読書中は重複追加できず、読了後に再度積み直しが可能
• 積読アイテムの状態遷移（stacked / reading / done）と読了済みからの再積み直し
• 最も古い積読を自動で取り出す「pickup」と、特定の本を選んで読書を開始する機能
• 月単位にグルーピングされた積読／読書中／読了済みダッシュボード
• 不要になった積読アイテムを削除してリストを整理

demo.mp4

技術スタック

• バックエンド: Go 1.25, chi (ルーティング),
• フロントエンド: React 19, TypeScript 5, Vite 7
• CI: GitHub Actions（PR 作成時に go fmt を強制）
• 外部サービス: Google Books API（API Key 必須）

リポジトリ構成

.
├── backend/          Go 製 API・ドメイン・インフラ
│   ├── cmd/
│   ├── data/
│   └── internal/
│       ├── handler/
│       ├── infra/
│       ├── server/
│       └── service/
└── frontend/         React + Vite 製 SPA
    ├── src/
    │   ├── components/
    │   ├── hooks/
    │   ├── pages/
    │   └── assets/
    ├── public/
    └── dist/

必要環境

• Go 1.25 以上
• Node.js 20（18 以上でも動作する想定、Vite はアクティブ LTS を推奨）
• npm 9 以上
• Google Books API Key（Google Cloud Console で取得）

セットアップ手順

1. バックエンド

1. 環境変数ファイルをコピー

   cp backend/.env.template backend/.env

2. backend/.env を編集し、BOOKS_API_KEY に取得したキーを設定します。必要に応じて BOOKS_BASE_URL や STORAGE_BACKEND、TSUNDOKU_STORE_PATH を変更できます。
3. API を起動

   cd backend
   go run cmd/api/main.go

   HTTP サーバーは http://localhost:8080 で待機します。

2. フロントエンド

1. 依存関係をインストール

   cd frontend
   npm install

2. 開発サーバーを起動

   npm run dev

   Vite が http://localhost:5173 でアプリを提供し、/api へのリクエストは http://localhost:8080 にプロキシされます。

バックエンド環境変数

変数名	説明	既定値
BOOKS_API_KEY	Google Books API の認証キー（本番利用では必須）	""
BOOKS_BASE_URL	Google Books API のエンドポイント	https://www.googleapis.com/books/v1/volumes
STORAGE_BACKEND	積読ストレージの種別。現在は file のみ対応。	file
TSUNDOKU_STORE_PATH	ファイルストレージ利用時の JSON 保存パス	data/tsundoku.json

file バックエンドを使用すると、API 起動時にディレクトリと JSON ファイルが自動生成されます。

API リファレンス

ヘルスチェック

• GET /health → {"status":"ok"}

技術書検索

• GET /api/technical-books
  • クエリパラメータ
    • q (必須): Google Books に渡す検索クエリ
    • page (任意, デフォルト 1): フロント側のページ番号
    • startIndex (任意): Google Books の抽出開始位置（0 始まり）。指定がなければ page から自動算出。
    • orderBy (任意): relevance or newest
    • lang (任意): ISO 言語コード。all または未指定でフィルタなし。
  • レスポンスは TotalItems と 10 件単位の Items を含む JSON です。

例:

curl "http://localhost:8080/api/technical-books?q=golang&page=1"

積読機能

• GET /api/tsundoku?status=stacked|reading|done — 状態でフィルタ可能な積読一覧
• POST /api/tsundoku — Book と任意の Note / Priority を含む JSON を送信して積読へ追加
• POST /api/tsundoku/pickup — 最も古い積読を reading に変更
• POST /api/tsundoku/{id}/pickup — 指定 ID の積読を reading に変更
• POST /api/tsundoku/{id}/status — 任意の状態へ更新
• POST /api/tsundoku/{id}/restack — 読了済みアイテムを再び積読へ戻す（タイムスタンプ更新）
• DELETE /api/tsundoku/{id} — 積読アイテムを完全に削除

注意

• このプロジェクトではローカルで動作するアプリケーションを開発するため、積読データはバックエンド実行ディレクトリ配下の JSON に保存するようにしております。初期化したい場合は手動で削除してください。