本文へスキップ
公開日: 使った技術: next.js · supabase · postgresql · tiptap · yjs · cloudflare-workers · typescript

melomemo(メロメモ)

ライブの記憶を、セットリストと一緒に残して共有するWebサービス。Tiptap + Hocuspocus(Yjs)⁠によるメモリーの協同編集と版の履歴、書き込みはAPI・⁠読み取りは共有ハンドラに分けた構成、アーキテクチャ適応度関数によるルールの機械検証、PGroongaとpg_trgmを併用したPostgres内の日本語検索を実装。

ライブの記憶を、セットリスト(セトリ)と一緒に残して共有するWebサービス。名前は melody of memory からの造語。

本番環境: melomemo.app(新しいタブで開きます)

コンセプト

始まる前から、終わったあとまで。ライブの記憶を残しておく場所。

  • 記憶と感情が主役、セトリは思い出すための手がかり。同じライブでも、泣いた人もいれば拳を突き上げていた人もいる。曲ごとの言葉や写真を残し、同じ場にいた人の言葉も読める
  • ログインなしで読める。トップページはサービス紹介のLPではなく、ライブ・アーティスト・セトリを探せるポータルにした。登録は、記録しようとした操作の文脈で案内し、ログイン後は元の画面と操作に戻す
  • セトリはオープンな共有財産。公演日・会場・曲名・曲順といった事実の記録は CC BY-SA 4.0 で公開する。一方、メモリー(個人の記録)や外部サービス由来のデータは対象に含めず、ライセンスの境界をそのまま実装の境界にしている

機能紹介

  • セットリストの記録と参照: 楽曲データベースから検索して曲順を登録する。思い出せない曲は「不明・覚えてない」として残せる
  • ネタバレ防止: 開催中のツアーのセトリやメモリーは伏せて表示し、見たい人だけが開ける
  • メモリー: セトリと連動した曲ごとの感想、画像、リッチテキストでライブの体験を残す。仲間を招いて同じメモリーを同時に編集でき、変更の履歴から過去の版に戻せる
  • 参加の記録と統計: これから行くライブと行ったライブをまとめ、アーティスト別・会場別などの統計で振り返る
  • アーティスト・楽曲・会場・タイトル(ツアーやフェス)のページ: 演奏履歴や演奏回数を、ログインなしで読める
  • つながり: フォロー、フレンド、フィード、リアクション、通知、ブロック・通報

メモリーの協同編集(2つのウィンドウで同じメモリーを編集している様子。サービス紹介ページのデモ)

アーキテクチャ

melomemo の全体の構成。Vercel の Next.js が画面を出し、書き込みは Cloudflare Workers の user-api へ、読み取りは共有 Query をプロセス内で呼んで Supabase に届く。協同編集は Fly.io の Hocuspocus が受けて版を保存する。画像は Cloudflare Images、管理画面と管理 API は本体から分けた Workers

  • Next.js 16(App Router)+ Vercel: ユーザー向けの本体。サーバーコンポーネントを中心に、use cache で公開ページを配信する
  • Supabase(PostgreSQL + Auth): データと認証。ログイン状態はサーバー側のセッションで持つ
  • Cloudflare Workers + Hono: 書き込みの入口になる user-api と、本体から切り離した管理画面・管理API
  • Hocuspocus(Fly.io): 協同編集のための Yjs の同期サーバー
  • Cloudflare Images: 画像の配信。非公開のメモリーの画像は、閲覧できる人にだけ配信する
  • 外部API: Spotify・Apple Music(楽曲・アルバム)、Google Maps(会場)
  • モノレポ: apps/(web・user-api・admin-web・admin-api・hocuspocus)と packages/(ドメインロジック、共有Query、API契約、メモリー本文の形式など)を pnpm workspace で管理

設計の判断

判断はADRとして記録している。そのなかから、何に困り、何を比べ、何を引き換えにしたかが伝わるものを選んだ。

協同編集: エディタと同期サーバーを選び直す

メモリーには「同時に編集できること」と「版の履歴を持てること」の両方が要る。

  • 最初は協同編集の公式サポートを理由に Lexical を選んだが、Yjs のドキュメントとの変換で問題が出た。ProseMirror の step を使って差分を表示しやすい Tiptap に移した
  • 同期は SaaS(Liveblocks)で始めたが、外部サービスへの依存を減らし、永続化と認証を自分で組めるようにしたかった。y-websocket(永続化のフックがない)、PartyKit(別のサービスへの依存が増える)、Supabase Realtime(Yjs のプロトコルに対応しない)と比べ、Tiptap 公式の Yjs サーバーである Hocuspocus をセルフホストする形に移した。読み込みと保存のフックで、版を自分で作る
  • 引き換えに、同期サーバーの運用を自分で持つ
  • メモリー本文の形式は、Web・同期サーバーなど複数の実装が同じドキュメントを読み書きする。形式を独立したパッケージ(zodのスキーマ・正規化・変換)にし、知っている語彙は検証し、知らない語彙は壊さずに通す(前方互換)ことで、実装ごとの食い違いで本文が壊れないようにした

書き込みはAPIに、読み取りは共有ハンドラに

  • 当初は認可の多くを RLS(行レベルセキュリティ)に任せていた。しかし、サービスロールで動く経路では RLS が効かず、規則がSQLのポリシーとアプリのコードに分かれていた
  • 認可の正本を TypeScript に移し、書き込み(Command)は user-api に一本化した。トランザクション境界・認可・冪等性はここが持つ。Server Action は cookie やキャッシュの再検証を担う薄いアダプタとして残す
  • 読み取り(Query)もAPI経由にする案は、HTTPの往復が増え、use cache も使えなくなるので退けた。可視性の判定を含む Query のハンドラを共有パッケージに置き、Web はプロセス内で呼ぶ
  • 引き換えに、ハンドラは RLS に頼れなくなる。同じハンドラをユーザーの権限とサービスロールで実行して結果が一致することを、DB境界のテストで確かめている。RLS は匿名の遮断と単純な読み取りの規則に絞った
  • コードは横割りのレイヤーではなく、機能ごとの縦割り(core/<feature>/{data,domain,usecase,authz,schema,types})に置く

ルールを文書ではなくテストで守る(アーキテクチャ適応度関数)

  • 「どこからどこを import してよいか」といった規則を文書に書くだけでは守られず、違反が溜まっていた。AIエージェントと開発していると、ずれは同じ方向に系統的に起きる
  • 依存の向きは次の図のとおり。Web の入口(ページ・Server Action・キャッシュ)は、読み取りに共有 Query、書き込みに user-api を使い、lib/core の data と usecase を直接は呼ばない。lib/core の中は usecase から domain・authz・data への一方向で、core は Next.js や React、画面のコードを知らない。user-api も routes → application → adapters の一方向にしている

melomemo の依存の向き。Web の入口は、読み取りに共有 Query、書き込みに user-api を使い、lib/core の data と usecase を直接は呼ばない。lib/core の中は usecase から domain・authz・data へ一方向で、core は next・react・画面を import しない。user-api は routes から application、adapters へ一方向で、application は hono を知らない。禁止の向きは適応度関数が検査する

  • この向きを、eslint-plugin-boundaries や dependency-cruiser と比べたうえで、新しい依存を増やさない vitest + TypeScript Compiler API のテストで検査することにした。共有パッケージも、core は純粋な関数だけ、メモリー本文の形式は zod と yjs だけ、というように依存してよいものをテストで固定している
  • 既存の違反は一括で直すことを導入の前提にせず、棚卸ししてラチェット方式にした。増えたら失敗し、直したら一覧から消す
  • 同じ考え方で、生のクエリの置き場所、use cache に閲覧者ごとの読み取りを入れないこと、秘密を読むモジュールの宣言、一覧の読み取りがカーソル(キーセット)方式であること、DBを読む配信物がマイグレーションの後に出ることも検査している。commit の前、push の前、develop・main への push の CD で落ち、CD で落ちるとマイグレーションと配信に進まない

melomemo のアーキテクチャ適応度関数。1. 決まりは guidelines と ADR が正本で、変えるときはテストと同じ PR で直す。2. vitest と TypeScript Compiler API で、import の向き、生のクエリの置き場所、'use cache' と閲覧者、秘密と server-only、カーソル方式の一覧、DB を読む配信の順序を検査する。3. 既存の違反は KNOWN_VIOLATIONS に棚卸しし、増えたら失敗、直したら消す。4. commit 前、push 前、develop・main への push の CD で落とし、CD で落ちるとマイグレーションと配信に進まない

日本語の検索を Postgres の中で完結させる

  • pg_trgm だけでは、日本語でよく使う1〜2文字の語や、ひらがな・カタカナ、全角・半角の違いが当たらなかった
  • 外部の検索エンジンは、同期の仕組みとサーバーが一つ増えるうえ、日本語の語の途中の一致や打ち間違いに弱い。楽曲のドメインを別サービスに切り出す案も、トランザクションが分かれるので退けた
  • 「含む」は PGroonga、「似ている」(打ち間違い)は pg_trgm に担わせて併用する。正規化・点数・並びの段(完全一致 → 先頭一致 → 途中を含む → 似ているだけ)は、それぞれ1つの関数を正本にした
  • 引き換えに索引は2種類になり、正規化を変えたら索引をすべて作り直す

デザイン: 多色は意味のある場所にだけ

  • 色はインディゴ系を基調に、ダークモードに対応する。半透明の面(グラスモーフィズム)はデザイントークンにし、カードは「押せるもの」と「押せないもの」でバリアントを分けた。backdrop-filter が入れ子や変形で効かなくなる制約は、半透明の背景・枠・ハイライトの組み合わせで避けている
  • 多色のグラデーションは「同じライブを人それぞれの色で感じている」ことの表現として、ロゴマークとトップの波線のように意味を持てる場所にだけ置く。文字をグラデーションで塗ることはしない
  • 中央に縦に積むヒーローや順にフェードインする演出は使わず、実際のセトリやライブで画面を組む
  • 文言は「記憶」と「感情」を主語にし、感情を決めつけず、人による違いを眺めるトーンにする

開発・運用

  • AIエージェントとの開発: 実装の多くは AI エージェント(Claude Code など)と進めている。規約の正本を docs/guidelines/ とADRに置き、ディレクトリごとの要約をエージェントが自動で読む形にしている。E2E の増強と改善の提案を行う「探索」も、実装とは別に回す
  • ローカルのゲート: pre-push で型・単体テスト・契約の検査と、Playwright によるブラウザのE2E(登録、確認メール、ライブの登録、メモリーの作成と公開など)を実行する
  • CD: DBを直接読む配信物は、必ずマイグレーションの後に出す。新しい列を読むコードが先に出ると全員が使えなくなるため。この順序はCIの構成から適応度関数で検査する
  • 監視: Sentry にエラーだけを送り、アプリごとにタグで分ける
  • リリースノート: 変更は利用者に向けた言葉で リリースノート(新しいタブで開きます) に公開している