# Requirements Document

## Introduction

This feature adds a "referred by" field to the contacts system, enabling users to track referral relationships between contacts. This allows the CRM to capture and display which existing contact referred a new contact, supporting referral tracking and relationship mapping.

## Glossary

- **Contact_System**: The contacts management module within the Atomic CRM application
- **Referred_By_Field**: A reference field that links one contact to another contact who provided the referral
- **Contact_Record**: A single contact entity stored in the database
- **Contact_Form**: The user interface for creating or editing contact information
- **Database_Schema**: The Supabase PostgreSQL database structure for storing contact data
- **TypeScript_Interface**: The Contact type definition used throughout the application
- **UI_Component**: React components that render the contact forms and displays

## Requirements

### Requirement 1

**User Story:** As a sales representative, I want to record which existing contact referred a new contact to me, so that I can track referral sources and acknowledge referrers.

#### Acceptance Criteria

1. WHEN a user creates or edits a Contact_Record, THE Contact_Form SHALL display a "Referred by" field
2. THE Referred_By_Field SHALL allow selection of any existing Contact_Record from the Contact_System
3. THE Referred_By_Field SHALL display contact names in a searchable dropdown format
4. THE Referred_By_Field SHALL be optional and allow null values
5. WHEN a user selects a referring contact, THE Contact_System SHALL store the referring contact's identifier with the Contact_Record

### Requirement 2

**User Story:** As a sales representative, I want to view which contact referred another contact, so that I can understand referral relationships in my network.

#### Acceptance Criteria

1. WHEN a user views a Contact_Record with a referring contact, THE Contact_System SHALL display the referring contact's name
2. THE Contact_System SHALL render the referring contact's name as a clickable link
3. WHEN a user clicks the referring contact link, THE Contact_System SHALL navigate to the referring contact's detail page
4. WHEN a Contact_Record has no referring contact, THE Contact_System SHALL display an empty or null state for the Referred_By_Field

### Requirement 3

**User Story:** As a system administrator, I want the referred by relationship to be stored in the database, so that referral data persists and can be queried for reporting.

#### Acceptance Criteria

1. THE Database_Schema SHALL include a "referred_by_id" column in the contacts table
2. THE Database_Schema SHALL define "referred_by_id" as a foreign key reference to the contacts table
3. THE Database_Schema SHALL allow null values for the "referred_by_id" column
4. WHEN a referring contact is deleted, THE Database_Schema SHALL set the "referred_by_id" to null for affected Contact_Records
5. THE TypeScript_Interface for Contact SHALL include a "referred_by_id" property of type Identifier or null

### Requirement 4

**User Story:** As a developer, I want the referred by field to integrate seamlessly with existing contact components, so that the implementation is consistent with current patterns.

#### Acceptance Criteria

1. THE UI_Component SHALL place the Referred_By_Field in the ContactMiscInputs section
2. THE Referred_By_Field SHALL use the ReferenceInput component pattern consistent with other reference fields
3. THE Referred_By_Field SHALL follow the same styling and layout as other fields in the Contact_Form
4. THE Contact_System SHALL validate that a contact cannot refer themselves
5. THE Contact_System SHALL handle the referred_by_id field in all CRUD operations for contacts