Image Cast Platform Development Guide

Image Castを配信する専用のポッドキャストホスティングプラットフォームの開発ガイドです。セルフホスト型のPodcast配信システムで、Turborepoモノレポ構成を採用しています。

プロジェクト概要

セルフホスト型Podcast配信システム。Cloudflare Workers、Pages、R2を活用したモダンなアーキテクチャ。

技術スタック

ディレクトリ構成

```

podcast-platform/

├── apps/

│ ├── admin/ # 管理画面（React + Vite + Tailwind）

│ ├── web/ # 公開サイト（Astro SSG + Tailwind）

│ └── worker/ # API + Cron（Cloudflare Workers + Hono）

├── packages/

│ ├── shared/ # 共通型定義 ※未実装

│ └── rss-generator/ # RSSフィード生成 ※未実装

├── docs/

│ └── SETUP.md # セットアップ手順

├── turbo.json

├── pnpm-workspace.yaml

└── package.json

```

開発ガイドライン

1. 言語規約

**コミットメッセージとプルリクエストは日本語で記述すること。**

コードコメントやドキュメントも日本語を使用します。

2. テスト実行ルール

**`apps/worker` を変更した場合は必ずテストを実行すること。**

```bash

Worker API のテスト実行

cd apps/worker && pnpm test

または、プロジェクトルートから

pnpm test

```

`apps/web` や `apps/admin` の変更時はテスト不要（テストファイルが存在しないため）。

3. テストファイルの配置

Worker API のテストは `apps/worker/src/__tests__/` に配置:

4. 新機能追加フロー

1. 機能を実装

2. 対応するテストを `apps/worker/src/__tests/` に追加

3. `pnpm test` で全テストが通ることを確認

4. 日本語でコミットメッセージを書いてコミット

認証方式

**Cloudflare Access** で一元管理。APIキーは使用しません。

Worker側でのJWT検証

```typescript

import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(

new URL(`https://${TEAM_DOMAIN}/cdn-cgi/access/certs`)

);

// Cf-Access-Jwt-Assertion ヘッダーを検証

await jwtVerify(jwt, JWKS, { audience: ACCESS_AUD });

```

開発モードでは `IS_DEV=true` で認証をスキップします。

**重要**: Admin と Worker は同一の Access アプリケーションに登録が必要（AUD が異なると認証失敗）。

API エンドポイント

Episodes（エピソード管理）

| Method | Path | 説明 |

|--------|------|------|

| GET | /api/episodes | エピソード一覧 |

| GET | /api/episodes/:id | エピソード詳細 |

| POST | /api/episodes | 新規作成 |

| PUT | /api/episodes/:id | 更新 |

| DELETE | /api/episodes/:id | 削除 |

Upload（ファイルアップロード）

| Method | Path | 説明 |

|--------|------|------|

| POST | /api/episodes/:id/upload-url | Presigned URL 発行 |

| POST | /api/episodes/:id/upload-complete | アップロード完了通知 |

| POST | /api/episodes/:id/upload-from-url | URL から取得 |

| POST | /api/episodes/:id/transcription-complete | 文字起こし完了 |

| POST | /api/episodes/:id/artwork/upload-url | アートワークURL発行 |

| POST | /api/episodes/:id/artwork/upload-complete | アートワーク完了通知 |

Settings（設定管理）

| Method | Path | 説明 |

|--------|------|------|

| GET | /api/settings | 設定取得 |

| PUT | /api/settings | 設定更新 |

| POST | /api/settings/artwork/upload-url | アートワークURL発行 |

| POST | /api/settings/artwork/upload-complete | アートワーク完了通知 |

Templates（テンプレート管理）

| Method | Path | 説明 |

|--------|------|------|

| GET | /api/templates | テンプレート一覧 |

| POST | /api/templates | テンプレート作成 |

| GET | /api/templates/:id | テンプレート詳細 |

| PUT | /api/templates/:id | テンプレート更新 |

| DELETE | /api/templates/:id | テンプレート削除 |

Import / その他

| Method | Path | 説明 |

|--------|------|------|

| POST | /api/import/rss | RSSインポート |

| POST | /api/import/rss/preview | RSSプレビュー |

| GET | /api/deployments | デプロイ状況 |

| GET | /api/health | ヘルスチェック（認証不要） |

※ RSSフィード (`/feed.xml`) は Pages で静的配信

エピソードのステータス遷移

```

文字起こしあり（skipTranscription: false）:

draft → uploading → transcribing → scheduled → published

文字起こしスキップ（skipTranscription: true）:

draft → uploading → scheduled → published

```

R2 バケット構造

```

podcast-bucket/

├── episodes/

│ └── {slug}/

│ ├── meta.json # メタデータ

│ ├── audio.mp3 # 音声

│ ├── transcript.vtt # 文字起こし

│ └── artwork.jpg # エピソードアートワーク（任意）

├── templates.json # テンプレート一覧

├── index.json # エピソード一覧 + Podcast設定

├── feed.xml # RSSフィード

└── assets/

└── artwork.jpg # Podcastアートワーク（OGP画像としても使用）

```

開発コマンド

```bash

pnpm install # 依存関係インストール

pnpm dev # 全体開発サーバー

pnpm dev:worker # Worker（localhost:8787）

pnpm dev:admin # 管理画面（localhost:5173）

pnpm dev:web # 公開サイト（localhost:4321）

pnpm build # ビルド

pnpm test # Worker API テスト

pnpm deploy:worker # Worker デプロイ

pnpm deploy:admin # 管理画面デプロイ

```

環境変数

Worker (wrangler.toml)

Worker (secrets)

Admin

環境変数は不要（Vite プロキシと Worker routes で自動的に `/api/*` にルーティング）

AI Agent Instructions

When working on this codebase:

1. **Always write commit messages and PR descriptions in Japanese**

2. **Run tests after modifying `apps/worker`**: Execute `pnpm test` before committing

3. **Add tests for new features**: Create corresponding test files in `apps/worker/src/__tests__/`

4. **Respect the monorepo structure**: Use workspace dependencies correctly

5. **Follow authentication patterns**: Use Cloudflare Access JWT verification, not API keys

6. **Understand status transitions**: Respect the episode status flow when implementing features

7. **Check R2 bucket structure**: Ensure file paths match the documented structure

8. **Reference SETUP.md**: For detailed configuration steps, refer to `docs/SETUP.md`

Constraints