System Overview

Welcome to the official documentation for Leads Pilot.

Leads Pilot is a lightweight, multi-tenant B2B CRM and pipeline management software[cite: 1]. It is intentionally designed with zero external framework dependencies to ensure fast performance and secure data isolation[cite: 1].

Getting Started

To begin using Leads Pilot, you will log into your dedicated agency workspace. Every workspace operates in strict isolation, ensuring that all companies, contacts, and pipeline deals are securely scoped to your unique agency identity[cite: 1].

Understanding CRM Entities

Leads Pilot separates data into three distinct architectural layers to prevent duplication and improve relationship tracking.

Companies

Companies serve as the primary organizational accounts. A single company can house multiple contacts and active leads.

Contacts

Contacts are the human individuals associated with a company. You can add activities, notes, and log interactions against individual contacts[cite: 1].

Leads (Pipeline Deals)

Leads represent active sales opportunities. When adding a new lead to the pipeline, you will associate it with an existing Company and Contact.

    Separating entity management into Companies, Contacts, and Deals/Leads is the standard architecture across CRM platforms (such as Salesforce or HubSpot) because each entity represents a distinct conceptual layer in B2B transactions:

    Companies (Accounts): Represent the organizational entity (e.g., Acme Corp).

    Contacts: Represent individual human beings who work at that company (e.g., Jane Doe, VP of Marketing).

    Leads / Deals: Represent a active, temporal sales opportunity or pipeline card (e.g., $15,000 Web Design Project).

While having separate entry mechanisms for Companies and Contacts alongside "Add New Lead" might initially seem redundant, using "Associated Company" and "Associated Contact" fields inside the Add New Lead flow is both practical and essential for agency workflows.
Why the Separate Entry Points Exist

    Database Normalization (Many-to-One / Many-to-Many Relationships):
    A single company may have multiple contacts (e.g., CEO, Procurement, IT Lead). Similarly, a single company or contact may have multiple active or past leads over time (e.g., a retainer deal in 2025 and an upsell deal in 2026). If leads, contacts, and companies were all bundled into a single entry form without separation, agencies would suffer from duplicated data, inconsistent reporting, and lost activity history.

    Non-Sales Touchpoints:
    Agencies often add contacts or companies before an actual sales opportunity exists (e.g., importing event attendee lists, partner directories, or cold outreach lists).

Will Agencies Understand Why It's Structured This Way?

Yes—provided the UX/UI sets clear expectations.

Agencies accustomed to modern sales software expect relational mapping (linking a deal to a contact/company). However, friction or confusion can arise depending on how the "Add New Lead" form handles those associations:
Potential UX Pitfalls & Misunderstandings

    "Do I have to create the Company/Contact first?"

        Confusion: If a user opens "Add New Lead" and the "Associated Company" dropdown requires the company to already exist in the database, users get frustrated by having to leave their tab, create a company/contact, and come back.

        Solution (Inline Creation): The "Add New Lead" entry form should allow inline creation—letting users type a new company or contact name directly into the search/select field and click "Create new Company/Contact" on the fly without breaking their workflow.

    Lead vs. Contact Ambiguity:

        Confusion: Smaller agencies or teams transitioning from spreadsheets often confuse a "Lead" (the sales deal) with a "Contact" (the person). They might ask: "Why am I adding Jane Doe as a Lead AND as a Contact?"

        Solution: Labeling and context. Clarifying that a Lead is the Opportunity/Deal (with a dollar value, stage, and close date) while the Contact is the Person attached to it resolves this gap.

    Multi-Contact / Multi-Deal Realities:

        Practicality: By keeping companies and contacts separated, an agency rep can look at a single Company profile and see all associated Contacts, past notes, and active pipeline deals in one centralized view.

Best Practices for Lead Entry Design

To ensure agency users find the entry mechanisms intuitive rather than disjointed:

    Primary Quick Action ("Add New Lead"): Make the "Add Lead" modal the primary action button on pipeline views. Allow users to select existing Contacts/Companies via an auto-complete lookup or create new ones inline within the same form.

    Auto-Population: If a user clicks "Add New Lead" directly from a specific Company or Contact page, automatically pre-fill the "Associated Company" or "Associated Contact" fields.

    Contextual Helpers: Subtle microcopy under association fields (e.g., "Link this deal to a primary point of contact and company") reinforces the distinction between the sales opportunity and the people involved.

Agency Workspaces (Multi-Tenancy)

Your data is strictly partitioned. Leads Pilot utilizes workspace isolation per agency via an agency_id[cite: 1]. Every action you perform—from creating a lead to logging a note—is exclusively tied to your workspace[cite: 1].

Roles & Permissions

Access control is divided into specific user tiers to protect sensitive pipeline configurations[cite: 1].

Admin

Admins have full workspace management capabilities[cite: 1]. This includes access to the dedicated /archive.php portal where admins can review archived pipeline entries, restore them, or perform permanent entry purging[cite: 1].

Sales Rep / User

Sales Reps have operational access. They can manage the pipeline, add or move deals, and create contact activities or notes, but cannot permanently delete pipeline entries[cite: 1].

Moving Deals

Sales reps and users can actively manage the pipeline by advancing leads through various stages[cite: 1].

Archiving & Restoring

To keep the active pipeline clean, outdated or lost deals should be archived rather than immediately deleted. Only Admin users can restore archived entries or permanently purge them from the database[cite: 1].