CONTRIBUTING.md

Contributing to AI Client Acquisition System

Welcome! This guide will help you get started as a contributor.

Getting Started

1. Clone the repo

   git clone https://github.com/iDevBuddy/ai-client-acquisition.git
   cd ai-client-acquisition
   

2. Install dependencies

   npm install
   cd src/profiling/python-service && pip install -r requirements.txt && cd ../../..
   

3. Set up environment

   cp .env.example .env
   # Fill in your API keys — ask @iDevBuddy for access
   

4. Set up database

   • Create a Supabase project (free)
   • Run migration files from supabase/migrations/ in order

5. Start development

   # Terminal 1: Trigger.dev tasks
   npm run trigger:dev
   
   # Terminal 2: Python AI service
   cd src/profiling/python-service && python main.py
   

Project Architecture

Phase 1: FINDING (current)
  Discovery → Scraping → Pain Detection → Email Finding → AI Profiling → Scoring → Slack

Phase 2: OUTREACH (upcoming)
  Email sequences → LinkedIn messaging → Follow-ups → Reply handling

Code Conventions

• TypeScript for orchestration, discovery, and integrations
• Python for AI profiling service (FastAPI)
• Zod for runtime validation
• Use logger (pino) for all logging — no console.log
• Every LLM call must have a traceId
• Every external API call must go through retry.ts

Branch Strategy

main        → production-ready code
develop     → integration branch
feature/*   → new features
fix/*       → bug fixes

Pull Request Process

1. Create a feature branch: git checkout -b feature/your-feature
2. Make your changes
3. Test locally (see Testing section)
4. Push and create a PR against develop
5. Get at least 1 review before merging

Security Rules

⚠️ NEVER commit API keys or secrets

• .env is in .gitignore — keep it that way
• Use .env.example for templates (no real values)
• If you accidentally commit a key, rotate it IMMEDIATELY

Questions?

Reach out to @iDevBuddy on GitHub or Slack.