Skip to content

README.md

Latest commit

 

History

History
359 lines (262 loc) · 9.15 KB

README.md

File metadata and controls

359 lines (262 loc) · 9.15 KB

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:

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=your-sender-email@domain.com

# 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: test@example.com / 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