1 #!/usr/bin/env bash
2 set -euo pipefail
3
4 # LeadPulse — First-time setup
5 # Usage: ./setup.sh
6
7 echo "=== LeadPulse Setup ==="
8 echo ""
9
10 # ── Prerequisites ──────────────────────────────────────────────────────────
11
12 command -v python3 >/dev/null 2>&1 || {
13   echo "Error: python3 is required (3.12+). Install from https://python.org"
14   exit 1
15 }
16
17 command -v pip >/dev/null 2>&1 || {
18   echo "Error: pip is required. Run: python3 -m ensurepip"
19   exit 1
20 }
21
22 # Docker is optional but recommended
23 if command -v docker >/dev/null 2>&1; then
24   echo "✓ Docker detected — full stack available via: docker compose up -d"
25 else
26   echo "  Docker not found — you'll need PostgreSQL and Redis running locally."
27 fi
28
29 # ── Environment ─────────────────────────────────────────────────────────────
30
31 if [ ! -f .env ]; then
32   cp .env.example .env
33   echo "✓ Created .env from .env.example — edit with your values before starting."
34 else
35   echo "✓ .env already exists — skipping."
36 fi
37
38 # ── Python virtualenv ────────────────────────────────────────────────────────
39
40 if [ ! -d .venv ]; then
41   echo "Creating virtual environment..."
42   python3 -m venv .venv
43 fi
44
45 # shellcheck disable=SC1091
46 source .venv/bin/activate
47
48 echo "Installing Python dependencies..."
49 pip install -r requirements.txt --quiet
50 echo "✓ Dependencies installed."
51
52 echo ""
53 echo "=== Setup complete! ==="
54 echo ""
55 echo "Next steps:"
56 echo "  1. Edit .env with your DATABASE_URL, REDIS_URL and SECRET_KEY"
57 echo "  2. Run:  make migrate   (applies Alembic migrations)"
58 echo "  3. Run:  make dev       (starts API on http://localhost:8000)"
59 echo "  4. Run:  make worker    (in a second terminal — starts Celery)"
60 echo "  5. Or:   docker compose up -d --build  (full stack in one command)"
61 echo ""
62 echo "  Using Claude Code? CLAUDE.md has all the context you need."
63 echo "  claude    # Run from project root"

1  # LeadPulse
2
3 Lead scoring and webhook dispatch API for digital marketing agencies.
4 Track behaviour, auto-score leads, and push to any CRM when they're hot.
5
6 ## Features
7
8 - Real-time event ingestion (visits, clicks, form submissions)
9 - Configurable scoring engine with threshold-based triggers
10 - Async processing via Celery + Redis (non-blocking, high-throughput)
11 - Webhook delivery to any CRM with HMAC signatures
12 - Full Docker Compose stack — zero external dependencies for dev
13
14 ## Quick Start
15
16     git clone https://github.com/cultiva-ia/leadpulse.git
17     cd leadpulse
18     ./setup.sh
19
20 See [CLAUDE.md](CLAUDE.md) for all commands and architecture details.
21
22 ## Prerequisites
23
24 - Python 3.12+
25 - pip
26 - Docker (recommended for PostgreSQL + Redis)
27
28 ## Configuration
29
30     cp .env.example .env
31
32 Key settings: DATABASE_URL, REDIS_URL, SECRET_KEY,
33               WEBHOOK_SECRET, SCORING_THRESHOLD
34
35 ## Development
36
37     make dev       # API on http://localhost:8000
38     make worker    # Celery worker (separate terminal)
39     make test      # Run pytest suite
40     make lint      # ruff + mypy
41
42 ## Using with Claude Code
43
44 This project includes a `CLAUDE.md` that gives Claude Code full context.
45
46     claude    # Run from project root — reads CLAUDE.md automatically
47
48 Claude Code will understand the stack, available commands,
49 key files, and configuration without any extra prompting.
50
51 ## License
52
53 MIT — see [LICENSE](LICENSE)
54
55 ## Contributing
56
57 See [CONTRIBUTING.md](CONTRIBUTING.md)

1 MIT License
2
3 Copyright (c) 2026 LeadPulse Contributors
4
5 Permission is hereby granted, free of charge, to any person obtaining a copy
6 of this software and associated documentation files (the "Software"), to deal
7 in the Software without restriction, including without limitation the rights
8 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 copies of the Software, and to permit persons to whom the Software is
10 furnished to do so, subject to the following conditions:
11
12 The above copyright notice and this permission notice shall be included in all
13 copies or substantial portions of the Software.
14
15 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 SOFTWARE.

1  # Contributing to LeadPulse
2
3 ## Development Setup
4
5     git clone https://github.com/cultiva-ia/leadpulse.git
6     cd leadpulse
7     ./setup.sh
8     make migrate
9     make dev
10
11 ## Branch Workflow
12
13 1. Fork the repo and create a branch: `git checkout -b feat/your-feature`
14 2. Make changes with tests
15 3. Run `make lint` and `make test` — both must pass
16 4. Open a PR against `main`
17
18 Branch naming:
19 - `feat/` — new features
20 - `fix/` — bug fixes
21 - `docs/` — documentation only
22 - `chore/` — maintenance, deps
23
24 ## Code Style
25
26 - **Formatter:** ruff format (line length 88)
27 - **Linter:** ruff check + mypy (strict mode on `app/`)
28 - **Types:** All public functions must be fully typed (Pydantic v2 models)
29 - **Tests:** New features require matching pytest tests in `tests/`
30 - **Commits:** Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`)
31
32 ## Reporting Issues
33
34 Use the GitHub issue templates:
35 - Bug? → `.github/ISSUE_TEMPLATE/bug_report.md`
36 - Feature? → `.github/ISSUE_TEMPLATE/feature_request.md`
37
38 Include your Python version, OS, and the output of `pip freeze`.
39
40 ## Using Claude Code
41
42 This project is Claude Code-ready. Run `claude` from the project root.
43 CLAUDE.md gives the AI full context: stack, commands, architecture,
44 key files, and configuration — no extra prompting needed.
45
46 Suggested prompts for contributors:
47 - "Add a new scoring rule for page_view events"
48 - "Write tests for the notifier retry logic"
49 - "Explain the data flow from event ingestion to webhook dispatch"