Resonance

---

What is Resonance?

Resonance (共振, gòngzhèn) is a social writing platform built around story cards. You write a piece of your life on a card: a title, a story, perhaps a photo. When someone else's card moves you, you don't tap a heart. You resonate with it, by writing a card of your own that answers it. The two cards are linked from then on, and so are the two of you.

It runs on the web at resonance.channel and as native apps for iPhone and Android, in Traditional Chinese and English. Anyone can read public cards without an account.

Why does it exist?

Most social apps measure attention: likes, views, time spent. What gets measured gets optimized, and the result is performance. Resonance is built on the opposite bet. It rewards only the response that costs something, which is writing.

• Resonance, not likes. The one public way to answer a card is to write another card. There are no like counts and no public comment threads, so nobody performs for an audience under someone else's story.
• Three ways to respond, each to someone. Bookmark a card (for yourself: private, never counted). Leave its author a note (for them alone: a letter nobody else reads). Or resonate (for everyone: a card of your own).
• Messages are earned through a story. There is no open inbox. Two people become connected when one resonates publicly with the other's card, or when an author answers a note, and only connections can message each other. Every conversation starts from a story, never from "hi". It is deliberately not a dating app.
• Anonymity per card. The account is real, but any single card can go out anonymously: no name, not on your profile. The server never tells anyone else who wrote it. The most vulnerable stories are often the ones most worth writing.
• AI as a mirror, not a judge. Before you publish, Resonance shows you the core insight it read in your draft. Recommendations come with the reason they were picked for you, and they are built from what you write, never from what you click or how long you looked. No score is ever shown.
• A safe room. Every card, person and message can be reported, and anyone can be blocked. No ads, no tracking. You can download everything you wrote, or delete your account.

The full reasoning, in Chinese, is in docs/product-design-principles.md.

Who is it for?

• Writers of real life: people who want to put a turning point, a small realization or a quiet memory into words, and be answered in kind.
• Readers who'd rather reply than react: people for whom a story is worth more than a number.
• Contributors: Resonance is open source. It is a working example of one product on three platforms (a Next.js site and SwiftUI and Jetpack Compose apps) over one versioned API, with a hand-drawn interface generated at runtime. If that interests you, read on.

Download

 

• iPhone: App Store
• Android: Google Play
• Web: resonance.channel. On a phone, resonance.channel/download opens the right store.

Features

Write cards	A warm paper editor for a title, a story (headings, quotes, pictures, links, other cards) and a cover photo, or a doodle illustration drawn from your story. Each card is for everyone, for your connections, or for you alone. Drafts save themselves.
Resonate	Answer a card with a card. A card's page shows the cards that answer it.
Notes	A private letter to a card's author. It connects you only if they write back.
Connections and messages	One-to-one conversations between people who met through a story, with replies, shared cards and link previews.
Thought map	Lay your own cards out on dotted paper: group them into regions, draw arrows and label how they relate.
Feeds	The latest public cards, and picks for you with the reason each was chosen.
Notifications	A bell on the web, and push notifications in the apps.
Safety and your data	Anonymous cards, blocking, reporting, data export, account deletion with a grace period.

How it's built

Web (Next.js + React)      iOS app (SwiftUI)      Android app (Compose)
          │                        │                        │
          └──────────── /api/v1 (Zod → OpenAPI) ────────────┘
                                   │
    Firebase Auth · Cloud Firestore · Cloudflare R2 · OpenAI · FCM

• Web: Next.js 15 (App Router), React 19, TypeScript (strict), next-intl, CSS Modules with OKLCH design tokens (no Tailwind), a Tiptap 3 editor that stores Markdown, SWR. Deployed on Vercel.
• Data: Cloud Firestore. The browser reads through security rules (firebase/firestore.rules); anything that reaches another person (publishing, notes, messages, pen names) goes through the server, which uses the Admin SDK and re-checks what the rules guarantee.
• API: /api/v1 is a contract. Zod schemas in src/lib/api/v1/schemas.ts generate openapi/v1/openapi.json, from which the iOS and Android clients are generated. It only changes additively.
• Apps: SwiftUI (apps/ios, XcodeGen) and Jetpack Compose (apps/android). They take their design tokens, strings, icons and story editor from the web (npm run apps:generate), so the web stays the single source.
• Images: Cloudflare R2, re-encoded on the server with sharp.
• AI (OpenAI, server-side only): English URL slugs, tag suggestions, story illustrations, the pre-publish insight, and recommendations (vector search over each card's insight, then a rerank that writes the reason).
• Design: hand-drawn shapes generated from seeds (src/lib/design), so the server and the browser draw the same wobble. See designs/DESIGN.md.

Where	What
src/app	pages ([locale]/…) and API routes (api/…)
src/components	atoms, molecules, sections
src/lib	auth, data layer, API contract, AI, push, storage, design geometry
src/messages	UI strings, en.json and zh-TW.json (the apps read them too)
firebase/	Firestore rules and indexes
apps/	the iOS and Android apps (apps/README.md)
test/	shared test setup; tests live next to their code
docs/	product principles, policies, store listings, architecture in Chinese

CLAUDE.md is the detailed, current architecture guide (written for AI coding agents and humans alike).

Getting started

You need Node.js 22 and npm. To run against local Firebase emulators (recommended; nothing touches real data) you also need Java 21 and the Firebase CLI (npm install -g firebase-tools).

git clone https://github.com/resonance-crew/Resonance.git
cd Resonance
npm ci

npm run emulators                  # terminal 1: Auth + Firestore emulators (project demo-resonance)
npx tsx scripts/seed-emulator.ts   # terminal 2: a small known world (alice, bob, carol, dora)
npm run dev:emulator               # http://localhost:3000, wired to the emulators

To sign in as a seeded account, open the browser console on the site and run await window.__emulatorSignIn('[email protected]', password). The password is SEED_PASSWORD in scripts/seed-emulator.ts; the helper exists only in emulator builds.

dev:emulator needs no secrets: it points Firebase at the emulators and leaves image storage off. Features that call OpenAI need OPENAI_API_KEY in a .env file (copy .env.example).

Checks

npm run lint
npm run typecheck
npm test                # Vitest: unit and component tests
npm run test:emulator   # Firestore rules and server suites against the emulators

The apps

Run the site for them on port 3100 (npm run dev:emulator -- --port 3100), then:

• iOS (Xcode and XcodeGen): cd apps/ios && xcodegen generate, build the Resonance scheme, and launch it with -emulator YES.
• Android (JDK 21 and the Android SDK): cd apps/android && ./gradlew :app:assembleDebug, and start it with --ez emulator true.

apps/README.md has the full commands, launch arguments and tests.

Contributing

Bug reports, fixes and ideas are welcome. Please read CONTRIBUTING.md first. In short: work on a branch, add a test that fails without your change, keep every string in both languages, build UI from the design system's primitives, and check it at desktop and phone widths.

Before proposing a feature, read the product principles above. Resonance will not add like counts, public comment threads or open messaging, however small.

Security

Please don't open a public issue for a vulnerability. Email [email protected] instead; SECURITY.md explains what to include and what happens next.

License

The source code is released under the MIT License, Copyright (c) 2026 resonance-crew.

The license covers the code. It does not cover the Resonance name, the wave logo or the app icons: please don't use them for your own product, and give a fork you publish its own name and icon. Fonts, flags and the store badges in this repository come from others under their own terms; see THIRD_PARTY_NOTICES.md.

Apple, the Apple logo and App Store are trademarks of Apple Inc. Google Play and the Google Play logo are trademarks of Google LLC.