Skip to content
Published: Built with: next.js · supabase · postgresql · tiptap · yjs · cloudflare-workers · typescript

melomemo

A web service for keeping and sharing memories of live concerts alongside their setlists. Features collaborative memory editing with version history (Tiptap + Hocuspocus/Yjs), writes routed through an API while reads use shared handlers, architecture fitness functions that check the rules as tests, and Japanese search kept inside Postgres with PGroonga and pg_trgm.

A web service for keeping and sharing memories of live concerts together with their setlists. The name is a coinage from melody of memory.

Production: melomemo.app(opens in a new tab) (Japanese)

Concept

From before the show starts until after it ends — a place to keep the memory of a live.

  • Memories and feelings come first; the setlist is a cue for remembering. At the same show, some people cried and others raised their fists. You can leave words and photos for each song, and read what others who were there wrote
  • Readable without logging in. The top page is not a landing page but a portal for finding lives, artists, and setlists. Sign-up is suggested in the context of what you were trying to record, and after logging in you return to the same page and action
  • Setlists are an open commons. Factual records — dates, venues, song titles, song order — are published under CC BY-SA 4.0. Memories (personal records) and data from external services are excluded, and that license boundary is also the implementation boundary

Features

  • Recording and browsing setlists: Register songs in order by searching the music catalog. Songs you can't recall can be kept as "unknown / don't remember"
  • Spoiler protection: Setlists and memories from tours still in progress are hidden until you choose to open them
  • Memories: Record the experience with per-song notes linked to the setlist, images, and rich text. Invite friends to edit the same memory at the same time, and restore earlier versions from the history
  • Attendance and statistics: Keep upcoming and past lives in one place, and look back with statistics by artist, venue, and more
  • Pages for artists, songs, venues, and titles (tours and festivals): Performance history and play counts are readable without logging in
  • Social features: Follows, friends, a feed, reactions, notifications, blocking and reporting

Collaborative editing of a memory (two windows editing the same memory; a demo from the service's About page)

Architecture

Overall architecture of melomemo. Next.js on Vercel renders the pages; writes go to the user-api on Cloudflare Workers, and reads call shared Query handlers in-process, both reaching Supabase. Hocuspocus on Fly.io handles collaborative editing and stores versions. Images are served by Cloudflare Images, and the admin UI and API run on Workers, split off from the main app

  • Next.js 16 (App Router) + Vercel: The user-facing app. Built mainly on server components, with public pages served through use cache
  • Supabase (PostgreSQL + Auth): Data and authentication. Login state is held in server-side sessions
  • Cloudflare Workers + Hono: The user-api that serves as the entry point for writes, and the admin UI and API, split off from the main app
  • Hocuspocus (Fly.io): A Yjs sync server for collaborative editing
  • Cloudflare Images: Image delivery. Images in private memories are served only to people allowed to view them
  • External APIs: Spotify and Apple Music (songs and albums), Google Maps (venues)
  • Monorepo: apps/ (web, user-api, admin-web, admin-api, hocuspocus) and packages/ (domain logic, shared queries, API contracts, the memory document format, and more), managed with pnpm workspaces

Design decisions

Decisions are recorded as ADRs. These are the ones that best show what the problem was, what was compared, and what was traded off.

Collaborative editing: choosing the editor and sync server again

A memory needs both simultaneous editing and a version history.

  • I first chose Lexical for its official collaboration support, but converting to and from the Yjs document caused problems. I moved to Tiptap, where ProseMirror steps make it easier to show diffs
  • Sync started on a SaaS (Liveblocks), but I wanted fewer external dependencies and control over persistence and authentication. Compared with y-websocket (no persistence hooks), PartyKit (another service dependency), and Supabase Realtime (no Yjs protocol support), I moved to self-hosting Hocuspocus, the official Yjs server for Tiptap. Its load and store hooks let me create versions myself
  • The trade-off is that I now operate the sync server
  • The memory document is read and written by several implementations, including the web app and the sync server. I made the format its own package (zod schemas, normalization, conversion) that validates the vocabulary it knows and passes through what it doesn't (forward compatibility), so a mismatch between implementations can't corrupt a document

Writes go through an API, reads through shared handlers

  • Originally much of the authorization was left to RLS (row-level security). But RLS doesn't apply on paths that run with the service role, and the rules were split between SQL policies and application code
  • I moved the source of truth for authorization to TypeScript and routed all writes (Commands) through the user-api, which owns transaction boundaries, authorization, and idempotency. Server Actions remain as thin adapters for cookies and cache revalidation
  • Routing reads (Queries) through the API as well was rejected: it adds an HTTP round trip and rules out use cache. Instead, Query handlers, including visibility checks, live in a shared package, and the web app calls them in-process
  • The trade-off is that handlers can no longer rely on RLS. DB-boundary tests run the same handler with user permissions and with the service role and check that the results match. RLS is now limited to blocking anonymous access and simple read rules
  • Code is organized by feature (core/<feature>/{data,domain,usecase,authz,schema,types}) rather than by horizontal layer

Enforcing rules with tests, not documents (architecture fitness functions)

  • Rules like "what may import what" were written down but not followed, and violations piled up. When developing with AI agents, drift tends to happen systematically in the same direction
  • The dependency directions are shown below. The web entry points (pages, Server Actions, caches) use shared Query handlers for reads and the user-api for writes, and never call lib/core data or usecase directly. Inside lib/core, usecase depends on domain, authz, and data in one direction, and core knows nothing about Next.js, React, or UI code. The user-api is also one-way: routes → application → adapters

Dependency direction in melomemo. The web entry points use shared Query handlers for reads and the user-api for writes, and never call lib/core data or usecase directly. Inside lib/core, usecase depends on domain, authz, and data in one direction, and core never imports next, react, or UI code. Inside the user-api, routes depend on application, which depends on adapters, and application doesn't know hono. Fitness functions check the forbidden directions

  • After comparing eslint-plugin-boundaries and dependency-cruiser, I chose to check these directions with vitest + the TypeScript Compiler API, adding no new dependencies. Shared packages have their allowed dependencies pinned by tests too: core may contain only pure functions, and the memory document format may depend only on zod and yjs
  • Instead of requiring every existing violation to be fixed first, I inventoried them and used a ratchet: the test fails if violations increase, and fixed ones are removed from the list
  • The same approach checks where raw queries live, that viewer-specific reads stay out of use cache, that modules reading secrets are declared server-only, that list reads use cursor (keyset) pagination, and that anything reading the database deploys after migrations. The checks fail before commit, before push, and in CD on pushes to develop or main, where a failure stops migration and deployment

Architecture fitness functions in melomemo. 1. Guidelines and ADRs are the source of the rules, changed together with the tests in one PR. 2. vitest and the TypeScript Compiler API check import directions, where raw queries live, viewer-specific reads in 'use cache', server-only for modules reading secrets, cursor pagination for lists, and that database readers deploy after migrations. 3. Existing violations are listed in KNOWN_VIOLATIONS; more fails the test and fixed ones are removed. 4. The checks fail before commit, before push, and in CD on pushes to develop or main, where a failure stops migration and deployment

Keeping Japanese search inside Postgres

  • pg_trgm alone missed one- and two-character words, which are common in Japanese, as well as differences between hiragana and katakana or full-width and half-width characters
  • An external search engine would add a sync mechanism and another server, and is weak at partial matches and typos in Japanese. Splitting the music domain into a separate service was also rejected because it would split transactions
  • PGroonga handles "contains" and pg_trgm handles "similar" (typos), used together. Normalization, scoring, and ranking tiers (exact → prefix → contains → similar only) each have a single function as their source of truth
  • The trade-off is two kinds of indexes, all of which must be rebuilt when normalization changes

Design: multiple colors only where they mean something

  • The palette is based on indigo, with dark mode support. The translucent surfaces (glassmorphism) are design tokens, and cards have separate variants for things you can press and things you can't. Because backdrop-filter stops working when nested or transformed, the look is built from a translucent background, a border, and a highlight instead
  • Multicolor gradients express that "everyone feels the same live in their own colors," so they appear only where they can carry that meaning, such as the logo mark and the waves on the top page. Text is never filled with a gradient
  • No centered, vertically stacked heroes or staggered fade-ins; screens are built from real setlists and lives
  • Copy uses memory and feeling as the subject, doesn't tell people what they felt, and treats differences between people as something to look at

Development and operations

  • Developing with AI agents: Much of the implementation is done with AI agents (such as Claude Code). The rules live in docs/guidelines/ and ADRs, with per-directory digests that agents load automatically. Separately from implementation, I run "exploration" passes that add E2E tests and propose improvements
  • Local gate: pre-push runs type checks, unit and contract tests, and browser E2E tests with Playwright (sign-up, confirmation email, registering a live, creating and publishing a memory, and more)
  • CD: Anything that reads the database directly is always deployed after migrations, because code that reads a new column before it exists would break the app for everyone. A fitness function checks this order from the CI configuration
  • Monitoring: Only errors are sent to Sentry, tagged by app
  • Release notes: Changes are published for users in plain language on the release notes(opens in a new tab) page (Japanese)