Murmurate: Platform for Grassroots Change

Move as one. Fund the change.

Murmurate is a community platform for grassroots changemakers — activists, organisers, mutual aid workers, and community leaders — to sustain their work, connect with supporters, and coordinate collective action. Named after the murmuration of starlings, where thousands of birds move as one without a central leader, Murmurate embodies the principle that powerful, coordinated change emerges from trust, proximity, and shared purpose.

---

🐦 What Is Murmurate?

For Changemakers

• Sustainable Funding — Receive recurring monthly support from a community of backers
• Transparent Impact — Log activities, publish updates, and track progress publicly
• Support Tiers — Create flexible funding options for different levels of support
• Supporter Engagement — Connect directly with people funding your work
• Trust Networks — Build credibility through public endorsements (vouches)

For Supporters

• Discover Work — Find changemakers doing work you believe in via directory and interactive map
• Fund Directly — Support creators with recurring monthly payments (no intermediary)
• Exclusive Access — Read supporter-only updates and activity logs
• Local Discovery — See needs and offers in your neighbourhood
• Community Participation — Engage through comments, reactions, and direct messaging

For Communities

• Mutual Aid Board — Post needs and offers; connect directly with each other
• Organisations — Create collective profiles for groups, unions, cooperatives, NGOs
• Interactive Map — Zoom from continent to street level; see who's organising locally
• Social Feed — Follow changemakers and stay informed about community action
• Direct Messaging — Connect privately with other community members

---

✨ Core Features

Feature	Description
Recurring Support	Monthly subscriptions to fund changemakers; custom tiers + amounts
Activity Logging	Dated records of work (training, outreach, direct action) with evidence
Posts & Updates	Long-form content with images, video, comments, and emoji reactions
Public Goals	Set funding/impact milestones; track progress transparently
Mutual Aid	Needs and offers board with urgency levels and location tagging
Interactive Map	Zoomable Leaflet map showing people, organisations, and mutual aid
Organisations	Collective profiles with membership roles and shared resources
Trust Network	Invite-based signup; public vouching system for accountability
Direct Messaging	Private conversations with configurable privacy controls
Social Feed	Timeline of posts and activities from people you follow
Supporter Export	CSV download of supporter emails for newsletters/outreach
Bitcoin (Roadmap)	Donate with Bitcoin; support for decentralised funding

---

🏗️ Technical Architecture

Tech Stack

Frontend:
- React 18 + Vite (bundler)
- Tailwind CSS + Radix UI (styling & components)
- Leaflet (interactive mapping)
- React Router (client-side routing)

Backend:
- Supabase (PostgreSQL, Auth, Storage, Real-time)
- Express.js (API server, Stripe webhooks)
- Stripe API (payment processing)

Infrastructure:
- Vercel (hosting + serverless functions)
- PostgreSQL (data persistence)
- S3-compatible storage (files & images)

Architecture Diagram

┌─────────────────────────────────────────┐
│   React App (Vite)                      │
│   - Pages: Directory, Map, Feed         │
│   - Components: Profile, Posts, etc.    │
└──────────────────┬──────────────────────┘
                   │ HTTP/WebSocket
                   │
┌──────────────────▼──────────────────────┐
│   API Layer (Express + Supabase)        │
│   - /stripe/checkout (payments)         │
│   - /stripe/webhook (subscription mgmt) │
│   - Row-Level Security (authorization)  │
└──────────────────┬──────────────────────┘
                   │ SQL Queries
                   │
┌──────────────────▼──────────────────────┐
│   Supabase Backend                      │
│   - PostgreSQL (data)                   │
│   - Auth (user accounts)                │
│   - Storage (files)                     │
│   - Real-time (live updates)            │
└─────────────────────────────────────────┘

---

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Supabase account (free tier available)
• Stripe account (for payments)

Installation

1. Clone the repository

git clone https://github.com/playnet/murmurate.git
cd murmurate

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env

Fill in the .env file with your credentials:

# Frontend (publicly safe to expose)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=eyJ...
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
VITE_APP_URL=http://localhost:5173
VITE_APP_API_BASE=http://localhost:8888

# Backend (keep secret!)
SUPABASE_SERVICE_KEY=eyJ...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

4. Set up the database

In your Supabase SQL editor, run the full schema:

-- Copy the entire contents of supabase/schema.sql
-- and paste into the Supabase SQL editor

This creates all tables, policies, and functions.

5. Create a storage bucket

In Supabase → Storage:

• Click "Create a new bucket"
• Name it: evidence
• Allow authenticated uploads

6. Start the development server

# Terminal 1: API server (Stripe webhooks, auth)
npm run api:start

# Terminal 2: Frontend (React dev server)
npm run dev

Visit http://localhost:5173 — you're running Murmurate locally!

Troubleshooting Setup

"Can't log in"

• Confirm you ran the full supabase/schema.sql
• Check that VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are correct
• Try signing up instead (you'll get a confirmation email)

"Activities won't log"

• Ensure RLS policies are applied (run supabase/schema.sql again)
• Log out and back in (this creates your profiles row)
• Check browser console for errors

"Images won't upload"

• Confirm the evidence bucket exists in Supabase Storage
• Check storage permissions in Supabase dashboard

---

📖 Documentation

Document	Purpose
GETTING_STARTED.md	User guide for first-time users, creators, supporters
USER_MANUAL.md	Step-by-step workflows (setup, funding, publishing, etc.)
FAQ.md	Frequently asked questions with detailed answers
DOCUMENTATION.md	Technical deep-dive (architecture, schema, API, development)
ABOUT.md	Vision & philosophy; implications for movements
STYLE_GUIDE.md	Brand assets and visual system

For Different Audiences

• I'm using Murmurate for the first time → Start with GETTING_STARTED.md
• I'm a creator/organiser → Read USER_MANUAL.md
• I have a question → Check FAQ.md
• I'm a developer → Read DOCUMENTATION.md
• I want to understand the philosophy → Read ABOUT.md

---

🛠️ Development

Running Tests

# Single run
npm run test:ci

# Watch mode
npm run test

Building for Production

npm run build

Output goes to /dist (automatically deployed by Vercel).

Project Structure

src/
├── pages/           # Route pages (React Router)
├── components/      # Reusable UI components
├── hooks/           # Custom React hooks
├── lib/             # Utilities, API clients
└── styles/          # Global CSS

api/
└── server.js        # Express API server

supabase/
├── schema.sql       # Database schema (source of truth)
└── migrations/      # Incremental migrations

public/
└── assets/          # Images, logos, icons

Code Standards

• Style: Follow existing conventions (check similar files)
• Tests: Write tests for new features
• Documentation: Comment complex logic
• No console.log() in production code
• Accessibility: Use semantic HTML, ARIA attributes

Making Changes

1. Create a feature branch

   git checkout -b feature/your-feature

2. Make changes and test

   npm run test:ci
   npm run build

3. Commit with co-author trailer

   git commit -m "Add feature: description
   
   Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"

4. Push and create a pull request

   git push origin feature/your-feature

---

🌐 Deployment

Murmurate deploys to Vercel automatically:

1. Connect your repository to Vercel
2. Set environment variables in Vercel dashboard
3. Push to main branch — Vercel builds and deploys automatically

Deployment includes:

• Frontend build (npm run build → /dist)
• Serverless API functions (/api/*.js)

---

🔐 Security

Data Protection

• Passwords: Hashed by Supabase Auth (bcrypt)
• Transit: All traffic over HTTPS
• At rest: PostgreSQL + Supabase encryption
• Files: S3-compatible storage with access controls

Authorization

All tables use Row-Level Security (RLS) — users only see data they own or that's shared with them:

• Private data is accessible only to the owner
• Public posts are readable by everyone
• Supporter-only posts are readable only by supporters
• Messages are readable only by sender/recipient

Secret Management

Never commit secrets:

• .env is in .gitignore (keep locally)
• Production secrets are in Vercel dashboard
• API keys are injected at runtime

---

🤝 Contributing

Reporting Issues

Create a GitHub issue with:

• Steps to reproduce
• Expected vs. actual behavior
• Environment (browser, OS)
• Screenshots/logs

Proposing Features

Open an issue with:

• Feature description
• Problem it solves
• Proposed solution
• Design mockups (if applicable)

Submitting Code

1. Fork the repository
2. Create a feature branch
3. Make changes + write tests
4. Submit pull request with description

See DOCUMENTATION.md for code standards.

---

📦 Dependencies

See package.json for full list. Key dependencies:

• react — UI framework
• vite — Build tool & dev server
• tailwindcss — Styling
• @radix-ui — Accessible components
• leaflet — Mapping
• @supabase/supabase-js — Database/auth client
• stripe — Payment processing
• express — API server
• vitest — Testing framework

---

📄 License

This project is licensed under the terms in LICENSE.

---

🐦 Philosophy

Murmurate is part of Playnet — a community of artists, activists, academics, and social impact workers exploring playful ways to build a better world.

We believe that:

• Movements own their own infrastructure, not platforms
• Grassroots workers deserve sustainable livelihoods
• Trust networks are human-legible, not algorithmic
• Collective action is beautiful and natural
• Play, creativity, and joy are essential to change

Read ABOUT.md for the full vision.

---

📞 Support

• Documentation — See links above
• Community — [Link to forum/chat]
• Report a bug — GitHub issues
• Contact — [support email]

---

Named for the murmuration — the breathtaking aerial dance of starlings moving as one, without a leader, guided only by awareness of their neighbours. That's the world we're building toward. 🐦