Quote Vote

A text-first civic engagement platform for creating posts, voting on specific text passages, and thoughtful discussions. Built with React/GraphQL frontend and Node.js backend, featuring targeted voting, quotes, social features, and moderation tools for transparent public dialogue.

🚀 Features

Core Functionality

• Text-First Posts: Create and share detailed text-based content
• Targeted Voting: Vote on specific text passages within posts
• Quote System: Highlight and discuss specific quotes from content
• Social Features: User profiles, following, and activity feeds
• Moderation Tools: Admin panel for content moderation and user management
• Real-time Chat: Live discussions and reactions on posts
• Search & Discovery: Advanced search functionality with filters
• Rich Link Previews: Dynamic Open Graph metadata so shared quote links display the quote title, author, and text preview in iMessage, Facebook, Twitter, Slack, and other platforms

User Experience

• Responsive Design: Works seamlessly across desktop and mobile devices
• Material-UI Components: Modern, accessible interface components
• Real-time Updates: Live notifications and activity updates
• Dark/Light Themes: Customizable user interface themes
• Accessibility: WCAG compliant design with screen reader support

🎥 Demo Videos

See Quote Vote in action! Watch our demonstration videos to get a quick overview of the platform's features and functionality:

Windows Demo

Platform demonstration on Windows

Linux Demo

Platform demonstration on Linux

These videos showcase:

• Creating and voting on posts
• Highlighting and discussing quotes
• Using the moderation tools
• Navigating the user interface

🛠 Tech Stack

Frontend (client/)

• React 17 - UI framework
• GraphQL - Data querying with Apollo Client
• Material-UI - Component library
• Redux Toolkit - State management
• Vite - Build tool and dev server
• Vitest - Testing framework
• Cypress - E2E testing
• Storybook - Component documentation

Backend (server/)

• Node.js - Runtime environment
• Express - Web framework
• Apollo Server - GraphQL server
• MongoDB - Database with Mongoose ODM
• JWT - Authentication
• WebSocket - Real-time subscriptions
• Stripe - Payment processing
• Nodemailer - Email functionality

📁 Project Structure

monorepo/
├── client/                 # React frontend application
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── views/          # Page components
│   │   ├── layouts/        # Layout components
│   │   ├── graphql/        # GraphQL queries/mutations
│   │   ├── store/          # Redux store configuration
│   │   └── utils/          # Utility functions
│   ├── netlify/
│   │   └── edge-functions/ # Netlify Edge Functions (OG metadata)
│   ├── public/             # Static assets
│   ├── cypress/            # E2E tests
│   └── docs/               # Documentation
├── server/                 # Node.js backend application
│   ├── app/
│   │   ├── data/           # GraphQL schema and resolvers
│   │   ├── types/          # Type definitions
│   │   └── utils/          # Utility functions
│   ├── tests/              # Unit and integration tests
│   └── dev_db/             # Development database setup
├── package.json            # Monorepo configuration
└── README.md

🚀 Getting Started

Prerequisites

• Node.js >= 18
• npm >= 8
• MongoDB (local or cloud instance)

Installation

1. Clone the repository

   git clone <repository-url>
   cd monorepo
   

2. Install all dependencies (Monorepo Setup)

   # Install dependencies for both client and server
   npm run install:all
   # or
   npm install --legacy-peer-deps
   

   Alternative: Install individual workspaces

   # Install only client dependencies
   npm run install:client
   
   # Install only server dependencies
   npm run install:server
   

3. Environment Setup

   Create .env files in both client/ and server/ directories:

   Server Environment Variables:

   NODE_ENV=development
   PORT=4000
   DATABASE_URL=mongodb://localhost:27017/quote-vote
   JWT_SECRET=your-jwt-secret
   STRIPE_SECRET_KEY=your-stripe-secret
   EMAIL_SERVICE=your-email-service
   EMAIL_USER=your-email-user
   EMAIL_PASS=your-email-password
   

   Client Environment Variables:

   REACT_APP_API_URL=http://localhost:4000/graphql
   REACT_APP_WS_URL=ws://localhost:4000/graphql
   

4. Start Development Database

   npm run dev-db-start --workspace=server
   

5. Run the Application

   Option 1: Run both client and server simultaneously

   npm run dev
   

   Option 2: Run individual services

   # Terminal 1 - Backend
   npm run dev:server
   
   # Terminal 2 - Frontend
   npm run dev:client
   

6. Access the Application

   • Frontend: http://localhost:3000
   • GraphQL Playground: http://localhost:4000/graphql

🧪 Testing

Run all tests

npm run test

Individual workspace testing

# Frontend tests
npm run test:client

# Backend tests
npm run test:server

Frontend specific testing

npm run cypress:open --workspace=client  # E2E tests

🏗️ Development Commands

Available Scripts

# Installation
npm run install:all        # Install all dependencies
npm run install:client     # Install client dependencies only
npm run install:server     # Install server dependencies only

# Development
npm run dev               # Run both client and server
npm run dev:client        # Run client only
npm run dev:server        # Run server only

# Building
npm run build             # Build both client and server
npm run build:client      # Build client only
npm run build:server      # Build server only

# Testing
npm run test              # Test both client and server
npm run test:client       # Test client only
npm run test:server       # Test server only

# Linting
npm run lint              # Lint both client and server
npm run lint:client       # Lint client only
npm run lint:server       # Lint server only

📚 Documentation

• Storybook: Component documentation and testing

  npm run storybook --workspace=client
  

• API Documentation: Available at GraphQL Playground
• Component Documentation: See client/docs/ for detailed guides

🔗 Open Graph / Link Previews

When a user shares a quote link (e.g. https://quote.vote/post/group/title/postId), the platform generates rich link previews that display the quote title, author name, and a text excerpt instead of the generic site name.

How It Works

The OG metadata system operates at three layers:

1. Netlify Edge Function (client/netlify/edge-functions/og-metadata.js)

   • Intercepts /post/* requests at the CDN edge before the page is served
   • Fetches post data from the GraphQL API
   • Rewrites the default OG meta tags in the HTML with quote-specific values
   • This is the primary mechanism — social media crawlers (iMessage, Facebook, Twitter, Slack) don't execute JavaScript, so they rely on the raw HTML meta tags

2. Server REST API (GET /api/og/:postId)

   • Returns OG metadata as JSON for a given post
   • Used as a fallback for non-Netlify deployments
   • Response: { title, description, image, url, type, siteName, authorName }

3. Client-side React Helmet (PostPage.jsx)

   • Updates meta tags dynamically after the React app hydrates
   • Acts as a secondary layer for browsers that do execute JavaScript

OG Title Format

Environment Variables

🚀 Deployment

Build for Production

# Build both applications
npm run build

# Or build individually
npm run build:client
npm run build:server

Frontend Deployment

npm run build:client
# Deploy the client/dist/ folder to your hosting service

Backend Deployment

npm run build:server
npm run start:server  # Uses PM2 for production

🔧 Troubleshooting

Common Issues

1. Peer dependency conflicts

   # Use legacy peer deps flag
   npm install --legacy-peer-deps
   

2. Babel installation issues

   If you encounter Babel runtime installation errors, use:

   npm install @babel/runtime --legacy-peer-deps
   

3. Port conflicts

   • Frontend: Change port in client/vite.config.js
   • Backend: Change PORT in server .env file

4. Database connection issues

   # Start development database
   npm run dev-db-start --workspace=server
   

5. Workspace-specific issues

   # Clear node_modules and reinstall
   rm -rf node_modules client/node_modules server/node_modules
   npm run install:all
   

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow the existing code style and conventions
• Write tests for new features
• Update documentation as needed
• Use conventional commit messages
• Test both client and server before submitting PRs

📄 License

This project is licensed under the LGPL-3.0 license - see the LICENSE file for details.

👥 Team

• Louis Girifalco - Creator
• Oliver Molina - Lead Developer
• Neo Isaac Amao - Developer
• Jovan Cahiles - Developer
• Camila Riedel - Designer
• Micah Shute - Developer
• Sarah Naas - Developer
• Mike Nayyar - Product
• David Nicholson - AI Developer
• Kira Rose Wojack - Operations
• Robert Palmer - Operations
• John May - Blockchain Developer
• Rafael Rodríguez - Developer
• Vishal Thukral - Developer
• Matt Polini - Developer
• Greddys Martinez - Designer
• Jason Ribble - Developer Operations
• Krishna Biradar - Backend Developer
• Brahmananda Reddy - AI Developer
• Akunna Nwosu - Developer
• Jay Evans - Mobile Developer
• Abed Gheith - Product
• Jon Kolman - Frontend Developer

🐛 Issues

If you encounter any issues, please:

1. Check the existing issues in the repository
2. Create a new issue with detailed information
3. Include steps to reproduce the problem

🔗 Links

• Repository: [GitHub Repository]
• Live Demo: [Demo URL]
• Documentation: [Documentation URL]

Built with ❤️ for transparent civic engagement and thoughtful public dialogue.