
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

Architecture
- 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) andpackages/(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/coredata or usecase directly. Insidelib/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
- 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
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-filterstops 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)