PipelineRemind

A simple, personal CRM application that allows users to manage their sales pipeline using a Kanban-style board. Track leads through customizable stages, automatically sync meetings from Fireflies.ai, and receive automated email reminders to follow up with leads.

Features

• 🎯 Kanban Board - Visual pipeline management with drag-and-drop functionality
• 📅 Meeting Tracking - Automatic sync with Fireflies.ai meeting recordings
• 📧 Email Reminders - Automated follow-up reminders via email
• 🏷️ Color Labels - Organize leads with customizable color coding
• 📬 Gmail Integration - Track email interactions with leads
• 🔔 Smart Notifications - Get notified when follow-ups are needed

Tech Stack

Frontend

• React with TypeScript and Vite
• React Router for navigation
• Tailwind CSS for styling
• shadcn/ui component library
• @dnd-kit for drag-and-drop functionality

Backend

• Node.js with Express
• TypeScript for type safety
• MongoDB with Mongoose ODM
• JWT for authentication
• Node-cron for scheduled jobs
• Postmark for email notifications

Integrations

• Fireflies.ai - Meeting transcription sync
• Gmail API - Email tracking
• Postmark - Transactional emails

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher)
• npm (v9 or higher)
• MongoDB (v6 or higher)

You'll also need accounts and API keys for:

• Fireflies.ai (optional)
• Google Cloud Console for Gmail OAuth (optional)
• Postmark for email notifications

Installation

1. Clone the Repository

git clone <repository-url>
cd PipelineRemind

2. Install Dependencies

The project uses a monorepo structure with client, server, and shared packages. Install all dependencies with:

npm install

This will automatically install dependencies for all packages (client, server, and shared).

3. Set Up MongoDB

Make sure MongoDB is running locally:

# Using mongod directly
mongod --dbpath /path/to/your/data

# Or using MongoDB service
sudo systemctl start mongod  # Linux
brew services start mongodb-community  # macOS

4. Configure Environment Variables

The server requires environment variables. These are already configured in server/.env:

# Server Configuration
PORT=3000

# Database
DATABASE_URL=mongodb://localhost/PipelineRemind

# Authentication
JWT_SECRET=your-jwt-secret-here
REFRESH_TOKEN_SECRET=your-refresh-token-secret-here

# Email Service (Postmark)
POSTMARK_API_KEY=your-postmark-api-key
FROM_EMAIL=[email protected]

# Application
APP_URL=http://localhost:5173

# Gmail OAuth (Optional)
GMAIL_CLIENT_ID=your-gmail-client-id
GMAIL_CLIENT_SECRET=your-gmail-client-secret
GMAIL_REDIRECT_URI=http://localhost:5173/api/gmail/callback

Note: For production, update these values with your actual credentials.

5. Seed the Database (Optional)

Create a test user and sample data:

npm run seed

This creates:

• Test user: [email protected] / password123
• Default columns (New Leads, In Progress, Closed)
• Sample leads with meetings

Running the Application

Development Mode

Start both client and server in development mode:

npm start

This runs:

• Client on http://localhost:5173
• Server on http://localhost:3000

Run Client or Server Separately

# Run only the client
npm run client

# Run only the server
npm run server

Build for Production

# Build all packages
cd server && npm run build

# Run production server
cd server && npm run start

Useful Scripts

Database Management

# Seed database with test data
npm run seed

# Initialize default columns for existing users
npm run init-columns

# Clean database (remove all data)
npm run clean-db

# Clean database and reseed
npm run clean-db && npm run seed

User Management

# Create an admin user
npm run create-admin

Testing

# Test Gmail integration
npm run test-gmail

# Run linting
npm run lint

Project Structure

PipelineRemind/
├── client/                 # React frontend
│   ├── src/
│   │   ├── api/           # API client functions
│   │   ├── components/    # React components
│   │   ├── contexts/      # React contexts
│   │   ├── hooks/         # Custom hooks
│   │   ├── pages/         # Page components
│   │   └── types/         # TypeScript types
│   └── package.json
│
├── server/                 # Express backend
│   ├── config/            # Configuration files
│   ├── jobs/              # Scheduled jobs (cron)
│   ├── models/            # Mongoose models
│   ├── routes/            # API routes
│   ├── scripts/           # Utility scripts
│   ├── services/          # Business logic
│   ├── utils/             # Helper functions
│   ├── server.ts          # Entry point
│   └── package.json
│
├── shared/                 # Shared code (types, configs)
│   ├── config/            # Shared configurations
│   ├── types/             # Shared TypeScript types
│   └── package.json
│
├── package.json           # Root package.json
└── README.md

API Documentation

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• POST /api/auth/logout - Logout user
• POST /api/auth/refresh - Refresh access token
• GET /api/auth/me - Get current user

Columns

• GET /api/columns - Get all columns
• POST /api/columns - Create new column
• PUT /api/columns/:id - Update column
• DELETE /api/columns/:id - Delete column
• PUT /api/columns/reorder - Reorder columns

Leads

• GET /api/leads - Get all leads
• POST /api/leads - Create new lead
• PUT /api/leads/:id - Update lead
• DELETE /api/leads/:id - Delete lead
• PUT /api/leads/:id/move - Move lead to different column

Meetings

• GET /api/leads/:leadId/meetings - Get meetings for lead
• POST /api/leads/:leadId/meetings - Create meeting
• PUT /api/meetings/:id - Update meeting
• DELETE /api/meetings/:id - Delete meeting
• POST /api/leads/:leadId/meetings/sync - Sync Fireflies meetings

Settings

• GET /api/settings - Get user settings
• PUT /api/settings - Update user settings
• POST /api/settings/fireflies/connect - Connect Fireflies
• POST /api/settings/fireflies/disconnect - Disconnect Fireflies
• POST /api/settings/test-reminder - Send test reminder email

Gmail

• GET /api/gmail/auth-url - Get OAuth URL
• GET /api/gmail/callback - OAuth callback
• GET /api/gmail/status - Check connection status
• POST /api/gmail/disconnect - Disconnect Gmail

Scheduled Jobs

The application runs two scheduled background jobs:

1. Reminder Check Job - Runs every 6 hours

   • Checks for overdue meeting reminders
   • Sends email notifications
   • Respects user notification preferences

2. Fireflies Sync Job - Runs every 2 hours

   • Syncs new meetings from Fireflies
   • Matches meetings to existing leads
   • Updates meeting records

Environment Variables Reference

Variable	Description	Required	Default
PORT	Server port	No	3000
DATABASE_URL	MongoDB connection string	Yes	-
JWT_SECRET	JWT signing secret	Yes	-
REFRESH_TOKEN_SECRET	Refresh token secret	Yes	-
POSTMARK_API_KEY	Postmark API key	For emails	-
FROM_EMAIL	Sender email address	For emails	-
APP_URL	Application URL	Yes	-
GMAIL_CLIENT_ID	Google OAuth client ID	For Gmail	-
GMAIL_CLIENT_SECRET	Google OAuth secret	For Gmail	-
GMAIL_REDIRECT_URI	OAuth redirect URI	For Gmail	-

Troubleshooting

MongoDB Connection Issues

# Check if MongoDB is running
sudo systemctl status mongod  # Linux
brew services list            # macOS

# Check MongoDB logs
tail -f /var/log/mongodb/mongod.log

Port Already in Use

If ports 3000 or 5173 are in use:

# Find and kill process using port 3000
lsof -ti:3000 | xargs kill -9

# Or change the port in server/.env
PORT=3001

Dependencies Issues

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

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please open an issue on GitHub.

Acknowledgments

• shadcn/ui for the beautiful component library
• Fireflies.ai for meeting transcription API
• Postmark for reliable email delivery