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**
   ```bash
   git clone https://github.com/iDevBuddy/ai-client-acquisition.git
   cd ai-client-acquisition
   ```

2. **Install dependencies**
   ```bash
   npm install
   cd src/profiling/python-service && pip install -r requirements.txt && cd ../../..
   ```

3. **Set up environment**
   ```bash
   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**
   ```bash
   # 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.