Pilot - Instagram Automation & Deal Management Platform

---

AI-powered Instagram automation for lead management and sales — built for creators, entrepreneurs, and social media managers to automate responses, manage contacts, and streamline deals.

📝 Table of Contents

• About
• Getting Started
• Deployment
• Usage
• Built Using
• Documentation
• Authors
• Acknowledgments

🧐 About

Pilot is an Instagram automation and deal management platform designed to help creators, entrepreneurs, small businesses, and social media managers transform their Instagram presence into a powerful lead generation and sales engine.

The platform features an AI-powered "Sidekick" that acts as a personalized assistant for managing deals, tracking progress, and providing intelligent recommendations. Users can automate responses to Instagram reels and interactions (e.g., replying 'YES' to receive resources or packages in their inbox), manage contacts with advanced scoring and filtering, and create custom automation workflows for repetitive tasks.

Built with modern web technologies, Pilot emphasizes AI-driven personalization, seamless Instagram integration, and user-friendly automations to streamline social commerce workflows. The platform is currently in active development and focuses on transparency through open-source practices.

🏁 Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Prerequisites

• Node.js (v18 or higher)
• pnpm package manager
• PostgreSQL database (or compatible like Neon)
• Instagram Developer Account (for API features)

Installing

1. Clone the repository

   git clone https://github.com/pilot-ops-crm/app.git
   cd app

2. Install dependencies

   pnpm install

3. Set up environment variables Copy .env.example to .env.local and configure.

4. Set up the database

   # Generate and run migrations
   pnpm db:generate
   pnpm db:migrate
   
   # Optional: Open Drizzle Studio for database inspection
   pnpm db:studio

5. Start the development server

   # Basic development server
   pnpm dev
   
   # Or run all services together (includes Inngest and database studio)
   pnpm dev:all

The application will be available at http://localhost:3000.

🔧 Running the tests

Currently, the project uses manual testing and user acceptance testing. Automated testing setup is planned for future releases.

Manual Testing

1. Development Testing

   • Run the development server with pnpm dev
   • Test core features: Instagram login, contact management, automation creation, sidekick interactions
   • Verify database operations and API endpoints

2. Integration Testing

   • Test Instagram API connections
   • Verify webhook functionality
   • Test real-time features and chat integration

3. User Journey Testing

   • Complete onboarding flow
   • Create and test automations
   • Manage contacts and view analytics

Code Quality Checks

Run linting and type checking:

# Lint the codebase
pnpm lint

# Type checking
pnpm typecheck

🎈 Usage

Core Features

1. Instagram Integration

   • Connect your Instagram account via OAuth
   • Set up automated responses to reels and stories
   • Configure lead capture from direct messages

2. Contact Management

   • View and organize Instagram contacts in a centralized table
   • Score contacts based on engagement and relevance
   • Add custom tags and notes for better organization
   • Filter and search through your contact database

3. Automation Workflows

   • Create custom automation templates
   • Set up triggers based on Instagram interactions
   • Configure automated responses and follow-ups
   • Monitor automation performance and logs

4. AI Sidekick

   • Set up your personalized AI assistant
   • Configure prompts and behavior preferences
   • Use for deal management and recommendations
   • Track conversation history and insights

5. Dashboard and Analytics

   • Monitor key metrics and performance
   • View automation success rates
   • Track contact engagement and conversion

Getting Started Workflow

1. Complete the onboarding process
2. Connect your Instagram account
3. Set up your first automation (e.g., "YES" response to reels)
4. Import or start collecting contacts
5. Configure your AI Sidekick preferences
6. Monitor and optimize your automations

For detailed guides, see the documentation folder.

🚀 Deployment

The project is configured for deployment on Vercel with the following services:

Production Deployment

1. Vercel Deployment

   • Connect your repository to Vercel
   • Configure environment variables in Vercel dashboard
   • Deploy automatically on pushes to main branch

2. Required Environment Variables

   BETTER_AUTH_SECRET=""
   BETTER_AUTH_URL=""
   
   DATABASE_URL=""
   
   GOOGLE_CLIENT_ID=""
   GOOGLE_CLIENT_SECRET=""
   
   POLAR_ACCESS_TOKEN=""
   POLAR_ORG_SLUG=""
   
   INSTAGRAM_CLIENT_ID=""
   INSTAGRAM_CLIENT_SECRET=""
   NEXT_PUBLIC_APP_URL=""
   
   NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=""
   CLOUDINARY_API_KEY=""
   CLOUDINARY_API_SECRET=""
   
   GOOGLE_GENERATIVE_AI_API_KEY=""
   
   NODE_ENV="development"
   
   SENTRY_AUTH_TOKEN=""
   SENTRY_DSN=""

3. Database Setup

• Use Neon PostgreSQL for production database
• Run migrations on deployment: pnpm db:migrate

4. Monitoring and Error Tracking

• Sentry is configured for error tracking and performance monitoring
• Check Sentry dashboard for any production issues

5. Domain Configuration

• Configure custom domain in Vercel
• Update NEXTAUTH_URL to match your domain

Additional Services

• Inngest: For data ingestion and workflow automation
• Polar: For payments and subscriptions
• Cloudinary: For image management and optimization

Waitlist Integration (src/app/api/waitlist/route.ts)

The main app integrates with the marketing website (pilot-ops.vercel.app) through a secure API connection for waitlist functionality.

Setting up WAITLIST_API_TOKEN

To connect the marketing site to this app, you need to set the same token in both repositories:

1. Generate a secure token (any random string like your-super-secret-token-12345)
2. Add to this app (pilot-ops-crm/app): Set WAITLIST_API_TOKEN=your-token-here in your .env.local
3. Add to marketing site (pilot-ops-crm/website): Set WAITLIST_API_TOKEN=your-token-here in their .env.local

The token can be simple - just make sure it's identical in both places and keep it secure in your environment variables.

How It Works

• The marketing site collects waitlist signups and sends them to this app's /api/waitlist endpoint
• This app verifies the token and processes the waitlist data
• The marketing site gets a response and shows success/error messages to users

This setup keeps the marketing site lightweight while letting the main app handle all the real data processing.

⛏️ Built Using

Core Framework

• Next.js - React Framework with App Router
• React - UI Library (v19.1.1)
• TypeScript - Type Safety
• Node.js - Runtime Environment

Database & ORM

• Drizzle ORM - Database Toolkit
• PostgreSQL - Primary Database
• Neon - Serverless PostgreSQL

Authentication & Authorization

• Better Auth - Authentication System
• NextAuth.js - Authentication Integration

UI & Styling

• Tailwind CSS - Utility-First CSS Framework
• shadcn/ui - Modern UI Components
• Radix UI - Headless UI Components
• Lucide React - Icon Library

AI & External APIs

• Vercel AI SDK - AI Integration
• Google AI - AI Provider
• Instagram API - Social Media Integration

Development & Deployment

• Vercel - Deployment Platform
• pnpm - Package Manager
• ESLint - Code Linting
• Sentry - Error Tracking & Performance Monitoring

Additional Libraries

• React Hook Form - Form Management
• TanStack Table - Data Tables
• Motion - Animation Library
• date-fns - Date Utilities
• Zod - Schema Validation

✍️ Authors

• ArjunCodess - Project development and maintenance

Note: This project embraces open-source values and transparency. We love open source because it keeps us accountable, fosters collaboration, and drives innovation. For collaboration opportunities or questions, please reach out through the appropriate channels.

🎉 Acknowledgements

• Instagram for providing the API that powers our social media integrations
• Vercel for the excellent deployment platform and AI SDK
• Neon for reliable serverless PostgreSQL hosting
• shadcn/ui and Radix UI for beautiful, accessible component libraries
• Drizzle Team for the powerful ORM toolkit
• Open Source Community for the countless libraries and tools that make modern web development possible

---

Pilot - Transforming Instagram interactions into business opportunities

Built with ❤️ for creators and entrepreneurs