Echo – A Shared Emotional Space for Couples & Families

Echo is a small, privacy-focused app for couples to share their emotional “vibes”, send glows (appreciations), and open up talk topics.
It’s built as a fun side project and a gift, but the codebase is fully open-source and easy to self‑host.

What you can do

• Track vibes together: Each person sets their current vibe so everyone has a sense of the room.
• Send glows: Lightweight appreciations that accumulate over time.
• Talk prompts: Soft entry points for deeper conversations.
• Weekly connections: Once per week both people check on each other and their current feelings with a 15 minute custom made bonding activity.
• Shared space model: Everything is scoped to a family / space (multi-tenant via Supabase).

---

Tech Stack

• Framework: Next.js App Router (/app)
• Runtime: React 19, TypeScript
• Auth & DB: Supabase (Postgres + Auth + RLS)
• UI: Tailwind CSS, custom components, a bit of 3D via three / @react-three/fiber
• PWA & Notifications:
  • @ducanh2912/next-pwa
  • Web Push (web-push) with VAPID keys

---

Getting Started

1. Clone & install

git clone https://github.com/Splestule/Echo.git
cd Echo
npm install

2. Environment variables

Create a .env.local file in the project root:

cp .env.example .env.local

Then fill in your own values:

• Supabase
  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_ROLE_KEY
• App base URL
  • NEXT_PUBLIC_BASE_URL (e.g. http://localhost:3000 in dev, your URL in prod)
• Web Push
  • NEXT_PUBLIC_VAPID_PUBLIC_KEY
  • VAPID_PRIVATE_KEY

You can generate VAPID keys with web-push (see comments in the SQL files under sql/ or the web-push docs).

3. Database setup (Supabase)

Point a Supabase project at this app and run the root schema file in the Supabase SQL editor:

1. Open schema.sql (root of the repo).
2. Paste it into the Supabase SQL editor and run it.

This script will:

• Create the core tables (profiles, families, vibes, glows, checkins, notifications, etc.)
• Set up RLS policies so each user only sees data for their family
• Add necessary RPC helpers for the app

Under the sql/ folder you’ll also find the same schema split into smaller files (policies, notifications, check-ins, realtime, etc.) if you prefer to inspect or run parts of it.

4. Run the dev server

npm run dev

Then open http://localhost:3000.

The first user to sign up will be prompted to create a space (family); later users can join an existing space via an invite code (the family UUID).

---

Production / Deployment

The app is designed to run on platforms like Railway or Vercel, with Supabase as the external database.

1. Set environment variables in your hosting platform (same as .env.local).
2. Build & start:

npm run build
npm start

The build script creates a standalone Next.js server bundle suitable for hosting on Railway (.next/standalone).

User data and sessions live in Supabase, not in the app container, so you can redeploy safely without losing data or logins (as long as you keep the same Supabase project and env vars).

---

Add to Home Screen

Echo works as a Progressive Web App (PWA) and can be installed on your phone's home screen for quick access.

iOS (Safari)

1. Open Echo in Safari (not Chrome or other browsers).
2. Tap the Share button (square with arrow pointing up) at the bottom of the screen.
3. Scroll down and tap "Add to Home Screen".
4. Customize the name if you want, then tap "Add".

The app will appear on your home screen and open in a standalone window without the Safari browser UI.

Android (Chrome)

1. Open Echo in Chrome.
2. You may see a banner at the bottom prompting you to "Add Echo to Home screen" — tap it.
3. If you don't see the banner:
   • Tap the menu (three dots) in the top right.
   • Select "Add to Home screen" or "Install app".
4. Confirm by tapping "Add" or "Install".

The app will appear on your home screen and can be launched like a native app.

Enable Notifications

After installing Echo to your home screen, you can enable push notifications to receive alerts when your partner sends you a glow or updates their vibe.

iOS:

• Open Echo from your home screen.
• Click the notification bell on top of the screen.

Android:

• Open Echo from your home screen.
• Click the notification bell on top of the screen.

Once enabled, you'll receive notifications even when the app isn't open, keeping you connected with your partner throughout the day.

---

Project Structure

• src/app – App Router pages, layouts, and server actions
  • auth/ – login, signup, setup, signout actions and callback route
  • actions/ – server actions for vibes, glows, talk, notifications, etc.
• src/components
  • features/ – feature-level components: vibes dashboard, check-ins, talk widgets, setup form
  • layout/ – layout pieces like Logo and NotificationBell
  • ui/ – simple stateless UI components (Button, Card, Input, …)
• src/hooks – client hooks for glows, vibes, notifications, talks
• src/utils/supabase – Supabase client helpers and schema types
• public – icons, manifest, service worker (sw.js, push-sw.js)

The debug/ folder under components is kept minimal and can be safely ignored or removed if you don’t need it.

---

Contributing

Contributions are very welcome – this is a small but opinionated codebase, and I’d love to see improvements.

• Read CONTRIBUTING.md for guidelines.
• For small fixes (typos, docs, small UI tweaks), feel free to open a PR directly.
• For larger changes, please open an issue first so we can align on scope.

---

License

This project is open source under the MIT License.
See LICENSE for details.

---

Made by Eduard Šimon