LeadPro — Lead Management System

A full-stack lead management platform for BD executives, software engineers, managers, and admins.

Stack

• Backend: FastAPI + SQLAlchemy + PostgreSQL + Celery + Redis
• Frontend: Next.js 15 + Tailwind CSS + Recharts

Features

• Auth & RBAC: Admin, Manager, BD Executive, Software Engineer roles
• User onboarding: Admin-provisioned accounts, BD self-registration with approval, email invite links
• Leads: Full CRUD, JD invite tracking, engineer/BD assignment, Phase → Type → Status hierarchy, history
• Monthly Targets: Engineer quotas by tech stack with progress tracking
• Profiles: Candidate registry with LinkedIn verification and GitHub tracking
• Issues: Engineers and BDs log issues; managers triage and resolve
• Reports: Dashboard KPIs, weekly/monthly reports with charts, SMTP email delivery
• Admin: User management, status config, audit log
• LLM Agents: Stub interfaces for lead enrichment and status suggestions

Architecture

Full write-up with module tables, permissions and improvement suggestions: docs/ARCHITECTURE.md · PDF copy: docs/architecture.pdf

System context

Four user roles reach one Next.js app, which calls the FastAPI backend. Celery with Redis runs scheduled reports and the daily AI job ingest.

Backend layers

Frontend

Data model

Request flow: changing a lead's status

AI pipeline

Besides the feed URL, the pipeline reads company boards on Greenhouse, Lever and Ashby. It keeps technical, remote, US-eligible jobs from the last 60 days, and closes a job after two complete fetches that no longer list it. Seed the board list once on a machine with internet access:

cd backend && python -m app.pipeline.probe

Deployment

Quick Start (one command)

cp .env.example .env   # then edit .env: set DATABASE_URL password, JWT_SECRET and ADMIN_PASSWORD
docker compose up -d postgres
./scripts/start.sh

Then open http://localhost:3000 and log in as [email protected] with the ADMIN_PASSWORD you set in .env.

Note: Postgres runs on port 5433 (not 5432) to avoid conflicts with a local PostgreSQL install.

Manual Start

Prerequisites

• Docker & Docker Compose
• Node.js 20+ (for local frontend dev)
• Python 3.12+ (for local backend dev)

Setup

cp .env.example .env
    docker compose up -d postgres redis
    # Postgres exposed on localhost:5433 (avoids conflict with local PostgreSQL on 5432)

Backend (local)

cd backend
python3 -m venv .venv
.venv/bin/pip install .
.venv/bin/uvicorn app.main:app --reload --port 8000

Ensure Postgres is running via Docker on port 5433 before starting the backend.

Frontend (local)

cd frontend
yarn install
yarn dev

Full Docker stack

docker compose up --build

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Demo Accounts

Role	Email	Password
Admin	[email protected]	admin123
Manager	[email protected]	manager123
BD	[email protected]	bd123456
Engineer	[email protected]	engineer123

Project Structure

lead-management-engine/
├── backend/          # FastAPI Python backend
├── frontend/         # Next.js frontend
├── docker-compose.yml
└── .env.example

cd backend && .venv/bin/uvicorn app.main:app --reload --port 8000 cd frontend && yarn dev