日本語は下に記載しています。

karaoke-api

Backend API for Karalis — a personal karaoke manager app (Flutter, iOS/Android).

Runs on Google Cloud Run and verifies Firebase Auth ID tokens for authentication.

---

Tech Stack

Framework	FastAPI (Python 3.11)
Hosting	Google Cloud Run
DB	Supabase / PostgreSQL
Auth	Firebase Admin SDK (ID token verification)
ORM	SQLAlchemy 2.0 + Alembic (migrations)
External API	Apple Music API (custom JWT / ES256 signing, 180-day cache)

---

Design notes

• N+1 prevention — SQLAlchemy selectinload() batch-loads related songs and history in a single query
• Apple Music JWT — Signs requests with ES256 using Apple's private key; tokens cached for 180 days to minimize regeneration
• DB indexes — Composite index on user_id + created_at for efficient list queries
• Cascade delete — Deleting an account removes all associated UserSong and SingingHistory records

---

Setup

Install dependencies

python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

Environment variables

Create a .env file:

DATABASE_URL=
FIREBASE_CREDENTIALS=
APPLE_MUSIC_KEY_ID=
APPLE_MUSIC_TEAM_ID=
APPLE_MUSIC_PRIVATE_KEY=

Run

uvicorn app.main:app --reload

→ http://localhost:8000

Migrations

alembic upgrade head

---

Deploy

gcloud run deploy karaoke-api \
  --source . \
  --region asia-northeast1

---

---

---

karaoke-api（日本語）

Karalis のバックエンドAPI。Flutter製カラオケ管理アプリ（iOS/Android）のサーバーサイド。Google Cloud Run上で動作し、Firebase AuthのIDトークンで認証を行う。

---

設計上の工夫

• N+1クエリ防止 — SQLAlchemyの selectinload() で関連データ（曲・履歴）を1クエリで一括取得
• Apple Music JWT — ES256でAppleの秘密鍵を署名、トークンを180日間キャッシュして再生成を最小化
• DBインデックス — user_id + created_at の複合インデックスで一覧取得を最適化
• カスケード削除 — アカウント削除時にUserSong・SingingHistoryを連動削除

---

セットアップ

依存関係のインストール

python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

環境変数

.env ファイルを作成:

DATABASE_URL=
FIREBASE_CREDENTIALS=
APPLE_MUSIC_KEY_ID=
APPLE_MUSIC_TEAM_ID=
APPLE_MUSIC_PRIVATE_KEY=

起動

uvicorn app.main:app --reload

マイグレーション

alembic upgrade head

デプロイ

gcloud run deploy karaoke-api \
  --source . \
  --region asia-northeast1