Company Management System - User Story

1. Problem Statement

User Roles Identified:

Sales Manager: Responsible for managing company relationships, tracking deals, and maintaining prospect information
Sales Representative: Handles day-to-day customer interactions, creates RFPs, and manages communication
Business Development Manager: Focuses on account growth, technology assessment, and strategic partnerships

Pain Points by Role:

Sales Manager:

Difficulty maintaining comprehensive view of all company relationships across multiple touchpoints
Limited visibility into technology stack and maturity levels of prospects
Challenges in tracking and prioritizing opportunities across the sales pipeline
Manual processes for managing company data and relationship mapping
Lack of integration between different communication channels and customer data

Sales Representative:

Time-consuming manual data entry for company information and contact details
Difficulty accessing complete company context during customer interactions
Challenges in managing multiple communication flows (emails, RFPs, meetings)
Manual process for creating and tracking RFPs with multiple stakeholders
Limited visibility into company's technology readiness and decision-making process

Business Development Manager:

Inability to assess prospect's technology maturity and integration capabilities
Difficulty tracking competitive positioning and win probability
Manual process for managing stakeholder relationships across complex sales cycles
Limited insights into company's automation level and analytics capabilities
Challenges in documenting and sharing competitive intelligence

Core Problem:

The current system lacks a unified platform for managing complex B2B relationships, resulting in fragmented data, manual processes, inefficient communication workflows, and limited visibility into prospect readiness and competitive positioning.

2. Who Are the Users Facing the Problem?

Primary Users:

Sales Manager: Oversees company portfolio, manages team performance, and strategic account planning
Sales Representative: Executes daily sales activities, manages customer communications, and handles RFP processes
Business Development Manager: Develops strategic partnerships, assesses market opportunities, and competitive analysis

Secondary Users:

Marketing Team: Utilizes company data for targeted campaigns and lead nurturing
Customer Success Team: References company profiles for onboarding and expansion opportunities

3. Jobs To Be Done

For Sales Manager: When I need to assess and prioritize opportunities across my portfolio, but I lack comprehensive visibility into each company's status, technology maturity, and relationship depth, help me get a unified view of all company relationships with real-time insights into deal progression and competitive positioning, so that I can make informed decisions about resource allocation and strategic focus.

For Sales Representative: When I need to engage with prospects and manage complex sales processes, but I'm spending too much time on manual data entry and searching for company context across multiple systems, help me streamline company data management and communication workflows with integrated tools for RFP creation and stakeholder management, so that I can focus more time on relationship building and closing deals.

For Business Development Manager: When I need to evaluate partnership opportunities and competitive positioning, but I lack visibility into prospects' technology readiness and decision-making processes, help me assess company maturity levels and track competitive intelligence with structured evaluation frameworks and stakeholder mapping, so that I can develop more effective partnership strategies and improve win rates.

4. Solution

The solution provides a comprehensive Company Management System within the CRM platform that centralizes all company-related information, automates routine tasks, and provides intelligent insights for better decision-making.

Key Capability Areas:

1. Company Profile Management

Centralized company database with comprehensive business information
Automated data enrichment and validation
Integration with external data sources for company insights

2. Contact Relationship Mapping

Visual stakeholder hierarchy and influence mapping
Contact role identification and decision-maker tracking
Relationship strength scoring and engagement history

3. Technology Assessment Framework

System aging and technology maturity evaluation
Integration readiness assessment
Competitive positioning analysis

4. Communication Management

Integrated email system with template library
Multi-channel communication tracking
Automated follow-up scheduling and reminders

5. RFP and Proposal Management

Structured RFP creation with stakeholder assignment
Section-based collaboration and deadline tracking
Win-loss analysis and competitive intelligence capture

6. Deal and Opportunity Tracking

Pipeline visualization with probability scoring
Deal stage progression with automated workflows
Revenue forecasting and performance analytics

7. Activity and Engagement Tracking

Comprehensive activity logging across all touchpoints
Meeting management with outcome tracking
Document sharing and collaboration history

8. Data Analytics and Insights

Company scoring algorithms based on multiple factors
Predictive analytics for deal success probability
Performance dashboards and reporting tools

9. Bulk Operations and Efficiency Tools

Bulk company import and data management
Mass communication capabilities
Automated data synchronization across systems

10. Integration and Automation

CRM integration with external business systems
Workflow automation for routine tasks
API connectivity for third-party data sources

5. Major Steps Involved

Sales Manager Flow:

Access Companies dashboard with filtering and search capabilities
Review company performance metrics (At Risk: 1, Open Opportunities: 7, No Recent Activity: 10)
Click on individual companies to view detailed profiles
Analyze technology maturity scores and competitive positioning
Review deal pipeline with weighted values and probability scores
Access team performance metrics and activity summaries
Export data for executive reporting and strategic planning
Configure alerts for high-priority account changes

Sales Representative Flow:

Navigate to Companies section from main menu
Create new company using "Add Company" button
Fill out company information form with required fields (name, email, industry, size, revenue, address)
Save company and access company detail page
Add contacts using "Attach Contacts" or "Add Contact" functionality
Search and select relevant contacts from existing database
Update contact relationships and roles within the company
Create and manage deals through "Add Deal" quick action
Send communications using integrated email system with templates
Log activities and meetings with detailed outcome tracking
Generate and track RFPs with multi-stakeholder workflows

Business Development Manager Flow:

Access company profiles to review technology assessment
Edit System Aging & Technology Maturity scores
Update technology stack information (CRM System, Marketing Tools, Analytics Platform)
Set automation levels and integration capabilities
Document competitive analysis and market positioning
Create strategic partnership proposals and track progress
Analyze win-loss patterns and adjust approach strategies
Generate competitive intelligence reports for team sharing

6. Flow Diagram

mermaid

flowchart TD
    A[Companies Dashboard] --> B[View Company List]
    B --> C{Action Required?}
    
    C -->|Add New Company| D[Add Company Form]
    D --> E[Fill Basic Information]
    E --> F[Add Company Details]
    F --> G[Save Company]
    G --> H[Company Profile Created]
    
    C -->|View Existing| I[Select Company]
    I --> J[Company Detail Page]
    
    J --> K{Management Action?}
    K -->|Manage Contacts| L[Attach/Add Contacts]
    L --> M[Search Contacts]
    M --> N[Select & Associate]
    N --> O[Update Relationships]
    
    K -->|Communication| P[Send Email]
    P --> Q[Select Recipients]
    Q --> R[Choose Template/Custom]
    R --> S[Compose & Send]
    
    K -->|Create RFP| T[RFP Creation Wizard]
    T --> U[Basic Info & Stakeholders]
    U --> V[Add Sections & Requirements]
    V --> W[Analysis & Submission]
    
    K -->|Manage Deals| X[Deal Management]
    X --> Y[Pipeline Tracking]
    Y --> Z[Opportunity Analysis]
    
    K -->|Technology Assessment| AA[Edit System Maturity]
    AA --> BB[Update Scores]
    BB --> CC[Save Assessment]
    
    H --> J
    O --> J
    S --> J
    W --> J
    Z --> J
    CC --> J

7. Business Rules

Companies Dashboard - Detailed Business Rules

KPI Cards Rules

Total Companies Card

Display Value: Shows total count of all companies in the system regardless of status - has a monthly filter button Filter Functionality: Dropdown displays "All time" by default; can be filtered by time periods (Last 30 days, Last 90 days, Last year, All time)
Calculation: Real-time count of all company records in the database

At Risk Card

Display Value: Shows count of companies flagged as requiring immediate attention
Risk Criteria: Companies with status "Churn Risk" OR no activity in last 90 days OR deals with close dates overdue by 30+ days OR negative sentiment indicators
Action Message: "Review to prevent churn" - clickable to filter companies list to at-risk companies only

Open Opportunities Card

Display Value: Shows count of companies with active deals in pipeline (not closed-won or closed-lost)
Inclusion Criteria: Companies with deals in stages: Prospect, Qualified, Proposal, Negotiation, Commitment
Action Message: "Focus sales efforts here" - clickable to show companies with open opportunities

No Recent Activity Card

Display Value: Shows count of companies with no recorded activity in defined timeframe
Activity Definition: No emails, calls, meetings, notes, or deal updates in last 60 days (configurable)
Action Message: "Re-engage before they go cold" - clickable to filter inactive companies

Header Controls Rules

Bulk Add Button - phase 2

Functionality: Opens bulk import modal for CSV/Excel file upload
File Requirements: Accepts .csv, .xlsx, .xls files up to 5MB
Required Columns: Company Name, Email (minimum); other fields optional
Validation Process: Pre-validates all data before import; provides error report for failed records
Permissions: Requires "Bulk Import" permission; typically admin or sales manager level
Progress Tracking: Shows import progress with success/failure counts

Attach Contacts Button

Functionality: Opens modal to associate existing contacts with companies
Search Capability: Search contacts by name, email, current company, or phone
Bulk Selection: Allows multiple contact selection with checkbox interface

Add Company Button

Functionality: Opens new company creation form modal

Form Validation: Enforces required fields (Company Name, Email) before submission

Duplicate Detection: Checks for existing companies with same name or email domain

FORM -

basic information - company name,website,email,phone,

company details - industry (with dropdown options and add custom industry field) , company size - 1-10,11-50,51-200,201-500,501-1000,1000+, annual revenue dropdown - less than 1M,-10,11-50,51-200,201-500,501-1000,1000+,

Adress information -

street address,city , state/province,ZIP/POSTAL CODE,country,description

Search and Filter Controls Rules

Global Search Bar

Search Scope: Searches across company name,Industry & Location ,website,
Search Behavior: Real-time search with 2+ character minimum; supports partial matching

Status Filter Dropdown

Options: All Statuses, Prospect, Active, Customer, Inactive, Churn Risk, Closed
Default Value: "All Statuses" showing all companies regardless of status
Multi-Select: Single selection only; cannot combine multiple statuses
Status Definitions:
- Prospect: Identified/added but minimal engagement (score typically 0-40)
- Active: Currently in discussions or nurturing phase (score typically 41-70)
- Customer: Closed deal, paying for product/service (score typically 71-100)
- Inactive: No activity for 90+ days, previously active (score typically declining)
- Churn Risk: Existing customers showing warning signs (declining usage, payment issues, complaints)
- Closed: No longer in play, either churned or lost to competitor (score typically 0-30)
Count Display: Shows count of companies in each status in dropdown

Industry Filter Dropdown

Options: All Industries, plus dynamic list of all industries present in company database
Industry Values: Education, Finance, Food & Beverage, Manufacturing, Energy, Healthcare, Technology, etc.

size range -

1. Micro Business

👥 1–10 employees

2. Small Business (SMB)

👥 11–50 employees

3. Lower Mid-Market

👥 51–200 employees

4. Upper Mid-Market

👥 201–500 employees

5. Mid Enterprise

👥 501–1000 employees

6. Enterprise / Corporate

👥 1000+ employees

Export Functionality Rules

Export CSV Button

exports all the data in table list in the csv file

Export Scope: Exports currently filtered/searched company list (not all companies if filters applied)
Column Inclusion: All visible columns in current view plus additional system fields
Data Fields: Company name, industry, location, contacts count, status, score, size, revenue, tags, created date, last activity
File Naming: "Companies_Export_YYYY-MM-DD_HHMMSS.csv"
Row Limits: Maximum 10,000 companies per export; pagination required for larger datasets
Permissions: Requires "Export Data" permission; audit logged for compliance
Processing: Background processing for large exports with email notification when complete

Company List Table Rules

Column Headers and Sorting

Company Column: Sortable alphabetically; displays company name, email, and website with company logo/initials
Industry & Location Column: Shows primary industry and city, state; sortable by industry then location
Contacts Column: Shows contact count with icon; sortable numerically; clickable to view contact list
Status Column: Color-coded status badges (green=active, blue=prospect, orange=churn risk, red=closed, gray=inactive)
Score Column: average score of all the contacts in the company
Size & Revenue Column: Shows company size category and revenue range; sortable by revenue value
Tags Column: Displays up to 3 tags with "+N more" if additional tags exist; no sorting
Actions Column: Three-dot menu with context-specific actions; not sortable

Row Data Display Rules

Company Logo: Shows uploaded logo or auto-generated initials badge with company name colors
Email Display: Shows primary company email; truncated if over 30 characters with tooltip showing full
Website Display: Shows domain only (not full URL); clickable to open in new tab
Contact Count: Shows total associated contacts; red indicator if no contacts associated
Status Color Coding:
- Active: Green background (#E8F5E8)
- Prospect: Blue background (#E3F2FD)
- Customer: Dark green background (#C8E6C9)
- Inactive: Gray background (#F5F5F5)
- Churn Risk: Orange background (#FFF3E0)
- Closed: Red background (#FFEBEE)
Score Display: Color-coded by ranges (0-40: Red, 41-70: Yellow, 71-100: Green)
Size Categories: small, medium, large (based on employee count ranges)
Revenue Formatting: Displays as abbreviated format ($60M, $150M, $200M)
Tags Styling: Colored tags with category-based color coding (industry tags blue, activity tags green, etc.)

Pagination and Performance Rules

Default Page Size: 50 companies per page
Page Size Options: 25, 50, 100, 200 companies per page
Performance Optimization: Lazy loading for large datasets; virtual scrolling for 200+ item pages
Navigation: Previous/Next buttons plus direct page number input
Total Count Display: Shows "Showing X-Y of Z companies" at bottom
State Persistence: Maintains current page, filters, and sorting when navigating away and returning
Loading States: Shows skeleton loading animation while fetching data

Add Company Button:

Display: Blue "Add Company" button with plus icon
Access Control: Available to authorized users only
Click Action: Opens company creation modal/form
Required Fields: Company name, industry, status
Validation: Real-time field validation
Save Options: "Save" and "Save & Add Another"

Attach Contacts Button:

Display: "Attach Contacts" button in header
Functionality: Opens contact selection interface
Selection Logic: Shows unattached contacts only
Bulk Attach: Allows multiple contact selection
Relationship Type: Defines primary/secondary contact roles
Confirmation: Shows attachment success message

Data Validation Rules:

Company Name:

Required field, cannot be empty
Maximum 100 characters
Must be unique across system
No special characters except apostrophes, hyphens, periods
Cannot start or end with whitespace

Email:

Valid email format required if provided
Maximum 150 characters
Domain validation against common business domains
Duplicate emails allowed across different companies

Industry:

Must be from predefined list
Cannot be null or empty
Case-insensitive matching
New industries require admin approval

Status:

Must be from defined status list (Active, Inactive, Prospect)
Cannot be null
Status changes trigger workflow events
Archive status available for System Admins only

Revenue:

Numeric values only
Non-negative numbers
Maximum value: $999,999,999,999
Supports decimal places for precise amounts
Currency symbol automatically added

Attach Contacts to Companies Modal

Company Selection Rules

Select Company Dropdown:

Field Type: Required single-select dropdown with search capability
Label: "Select Company" (required selection)
Default Value: "Choose a company..." placeholder text with dropdown arrow
Data Source: All companies from companies table excluding archived/deleted
Display Format: Company Name (e.g., "Acme Corporation", "TechCorp Solutions")
Search Functionality:
- Type-ahead search within company names
- Minimum 2 characters to trigger search
- Case-insensitive matching
- Partial word matching supported
- Search results limited to 50 companies maximum
Validation Rules:
- Selection is required before contacts can be displayed
- Must be from existing companies list
- Cannot select companies that are archived or inactive
- Previous selections cleared when changing company
Behavior:
- Dropdown opens on click or down arrow key
- Selection updates available contacts list immediately
- Clears any previous contact selections when changed
- Dropdown closes after selection made
Error Handling:
- "Please select a company" if user tries to attach without selection
- "Company not found" if search returns no results
- "No companies available" if all companies already have contacts attached

Search Contacts Rules

Search Input Field:

Field Type: Text input with search icon
Placeholder: "Search contacts by name, email, or current company..." (guidance text)
Search Icon: Magnifying glass icon on left side of input field
Clear Icon: "×" icon appears on right side when text entered
Search Scope: Searches across contact name, email address, and current company name
Search Logic:
- Real-time search with 300ms debounce delay
- Minimum 2 characters required to trigger search
- Case-insensitive partial matching using LIKE operator
- Searches multiple fields simultaneously (name OR email OR company)
- Results highlight matching text
- Special characters escaped to prevent SQL injection
Clear Function:
- "×" icon clears search field and shows all available contacts
- ESC key also clears search field
- Clearing search resets contact list to original state
Performance:
- Search limited to first 100 results with "Show more" option
- Search queries cached for 5 minutes
- Debouncing prevents excessive API calls
Empty State: Shows all available contacts when search field is empty
No Results State: Shows "No contacts found matching your search" message

Available Contacts Display Rules

Contact List Header:

Display Format: "Available Contacts (4)" - shows total count of available contacts
Count Logic:
- Updates dynamically based on search filters and company selection
- Shows filtered count when search applied
- Format: "Available Contacts (X)" where X is current visible count
Select All Checkbox:
- Label: "Select All (4)" - includes count of contacts that would be selected
- Position: Right side of header, aligned with individual checkboxes
- Functionality: Selects/deselects all visible contacts in current view
- State Indicators:
  - Unchecked: No contacts selected (empty square)
  - Checked: All visible contacts selected (checkmark in square)
  - Indeterminate: Some but not all contacts selected (dash in square)
- Behavior:
  - Checkbox state updates automatically based on individual selections
  - Clicking toggles all visible contacts
  - Maintains state during search operations
- Accessibility: Screen reader announces "Select all contacts" with current state

Individual Contact Cards Rules

Contact Card Layout:

Card Structure: Horizontal layout with checkbox, avatar, info, and metadata
Card Height: Fixed height to maintain consistent list appearance
Hover Effect: Background color change on hover
Selection State: Selected cards show visual indication with border and background change
Spacing: Standard padding inside card and margin between cards

Contact Selection Checkbox:

Position: Left side of each contact card, vertically centered
Size: Standard checkbox size
Functionality: Individual contact selection toggle
State Management:
- Updates "Select All" checkbox state when changed
- Maintains selection state during search/filter operations
- Selection persists until modal closed or contacts attached
- Visual feedback with checkmark animation
Accessibility:
- Keyboard accessible via Tab navigation
- Space bar toggles selection
- Screen reader announces contact name and selection state
Click Area: Extended click area includes contact name for easier selection

Contact Avatar:

Display: Circular avatar with contact initials
Position: Left side, adjacent to checkbox
Initial Logic:
- First letter of first name + first letter of last name
- Example: "Sarah Johnson" → "SJ"
- Single name uses first two letters: "Madonna" → "MA"
Color Scheme:
- Consistent color assignment based on name hash
- Multiple predefined colors for variety
- Same name always gets same color
Fallback: Generic user icon if name not available or initials cannot be determined
Size: Standard size for consistent appearance
Font: White text, bold weight

Contact Information Display Rules

Primary Contact Information:

Contact Name:
- Format: "FirstName LastName" (e.g., "Sarah Johnson")
- Font: Bold/semibold weight, larger size, dark text
- Position: Top line of contact information
- Handling: Shows "Unknown Contact" if name missing
- Character Limit: Truncated with ellipsis if exceeds maximum characters
Email Address:
- Format: Standard email format (e.g., "sarah.johnson@techcorp.com")
- Display: Second line, secondary text styling
- Font: Regular weight, smaller size
- Validation: Shows only validated email addresses
- Click Action: Opens default email client when clicked (mailto: link)
- Character Limit: Truncated with ellipsis if exceeds maximum characters
Current Company:
- Format: Company icon + company name (e.g., "🏢 TechCorp Solutions")
- Display: Third line, below email address
- Icon: Building icon from icon font
- Logic: Shows company currently associated with contact (if any)
- Handling: Shows "No Company" if not associated with any company
- Styling: Medium gray text

Secondary Contact Information (Right Side):

Job Title/Role:
- Format: Role text (e.g., "VP of Sales", "CTO", "Marketing Director")
- Display: Top right of contact card, aligned with contact name
- Font: Regular weight, medium gray text
- Handling: Shows "No Title" if job title not specified
- Character Limit: Truncated after specified character limit
Contact Score:
- Format: "Score: 95" (numeric score display)
- Position: Second line on right side, below job title
- Score Range: 0-100 scale integer values
- Visual Indication: Different styling based on score ranges:
  - High scores (90-100): Positive visual indication
  - Good scores (80-89): Good visual indication
  - Average scores (70-79): Neutral visual indication
  - Low scores (60-69): Caution visual indication
  - Poor scores (50-59): Warning visual indication
  - Very poor scores (Below 50): Alert visual indication
- Font: Bold weight, smaller size
- Tooltip: Hover shows score calculation breakdown
Last Activity Date:
- Format: "2024.01.20T14:30:02" (ISO format display)
- Display: Bottom right of contact card
- Font: Small text, light styling
- Logic: Shows most recent interaction/activity timestamp
- Handling: Shows "No Activity" if no recorded interactions
- Timezone: Displays in user's local timezone
- Relative Time: Shows "2 days ago" for recent activities on hover

Contact Status Indicators

Lead Status Badges:

Hot Lead Badge:
- Background: Alert/danger styling with white text
- Text: "Hot Lead"
- Priority: Highest priority contacts requiring immediate attention
Qualified Badge:
- Background: Primary/info styling with white text
- Text: "Qualified"
- Priority: Contacts that have been vetted and meet criteria
Nurturing Badge:
- Background: Warning styling with white text
- Text: "Nurturing"
- Priority: Contacts in ongoing relationship building phase
Badge Position: Top left of contact information area, above contact name
Badge Styling:
- Rounded corners
- Small font size
- Bold text weight
- Minimal padding
Logic: Based on contact.lead_status field from database
Multiple Badges: Maximum one badge per contact (highest priority shown)
Accessibility: Screen reader announces badge status with contact name

Contact Filtering and Sorting Rules

Available Contacts Logic:

Inclusion Criteria:
- Contacts not already attached to the selected company
- Active contacts only (contact.status = 'active')
- Contacts with complete profile information (name and email required)
- Contacts user has permission to view based on role
- Contacts not marked as "Do Not Contact"
Exclusion Criteria:
- Contacts already attached to selected company
- Inactive, archived, or deleted contacts
- Contacts with restricted access levels above user's clearance
- Duplicate contact records (deduplicated by email address)
- Contacts marked as competitors or restricted accounts
Sorting Logic:
- Primary Sort: Contact score (descending) - highest scores first
- Secondary Sort: Last activity date (most recent first)
- Tertiary Sort: Contact name (alphabetical A-Z)
- Quaternary Sort: Company name (alphabetical A-Z)
Pagination: 20 contacts per page with "Load More" button
Total Limit: Maximum 500 contacts shown to prevent performance issues

Attachment Validation Rules

Pre-attachment Validation:

Company Selection:
- Must have valid company selected from dropdown
- Company must be active and not archived
- User must have permission to modify selected company
Contact Selection:
- At least one contact must be selected via checkbox
- Maximum 50 contacts can be selected in single operation
- All selected contacts must still be available (not deleted since modal opened)
Duplicate Check:
- Prevents attaching contacts already associated with company
- Real-time validation during selection process
- Warning message for any duplicate attempts
Permission Check:
- User must have "Attach Contacts" permission for target company
- Contact modification permissions verified for each selected contact
- Admin override available for restricted contacts
Active Status:
- Both company and all selected contacts must have active status
- Inactive contacts cannot be attached (filtered out automatically)

Business Rule Validation:

Relationship Limits:
- No limit on contacts per company
- No limit on companies per contact (many-to-many relationship)
- Primary contact designation requires separate action
Data Integrity:
- Contact email addresses must be unique within company
- Cannot attach same contact to same company twice
- Relationship effective date defaults to current timestamp
Workflow Triggers:
- Attachment events trigger welcome email workflows
- CRM synchronization initiated for new relationships
- Notification sent to company administrators

Form Action Rules

Cancel Button:

Button Type: Secondary button with standard styling
Label: "Cancel" (fixed text, not translatable)
Position: Bottom left of modal footer
Size: Standard button dimensions
Click Action:
- Closes modal without saving any selections
- Shows confirmation dialog if contacts selected: "Are you sure? Selected contacts will not be attached."
- Confirmation options: "Yes, Cancel" and "Continue Selecting"
- Clears all selections when confirmed cancellation
- Returns focus to trigger element on main page
Keyboard Navigation:
- Accessible via Tab navigation
- Enter or Space key activates button
- ESC key triggers cancel action
State Management: Always enabled regardless of form state
Analytics: Tracks cancellation events for UX improvement analysis

Attach Contacts Button:

Button Type: Primary button with prominent styling
Label: Dynamic text based on selection count:
- "Attach 0 Contacts" (disabled state)
- "Attach 1 Contact" (enabled state)
- "Attach 3 Contacts" (enabled state)
- "Attach 50 Contacts" (maximum, enabled state)
Position: Bottom right of modal footer
Size: Auto-width based on text content, minimum width specified
Enable State Logic:
- Disabled when no company selected
- Disabled when no contacts selected
- Enabled when company and at least one contact selected
- Shows loading spinner when processing
Click Action:
- Validates all selections before processing
- Disables button and shows loading state during attachment
- Prevents double-click submissions via button state management
- Closes modal automatically on successful attachment
- Shows success toast message: "X contacts attached to [Company Name] successfully"
- Updates company contact count in main page company list
- Refreshes any open company detail views
Loading State:
- Button shows spinner icon and text changes to "Attaching..."
- Button disabled during processing to prevent multiple submissions
- Timeout after 30 seconds with error message if no response
Error Handling:
- Shows inline error message above button for validation failures
- Network errors show retry option: "Failed to attach contacts. Retry?"
- Server errors escalated to support with reference ID provided to user

Search and Filter Performance Rules

Search Performance:

Response Time: Search results must return within 500ms for optimal UX
Debounce Delay: 300ms delay after last keystroke before search executes
Query Optimization: Database indexes on searchable fields (name, email, company)
Result Limiting: Maximum 100 contacts per search to maintain performance
Progressive Loading: "Load More" button loads additional 20 contacts at a time
Caching Strategy: Search results cached in browser for 5 minutes
Background Refresh: Cache refreshed in background if data older than 2 minutes

List Performance:

Initial Load: Shows first 20 contacts immediately on modal open
Lazy Loading: Additional contacts loaded on scroll or "Load More" click
Virtual Scrolling: Implemented for lists over 100 items to optimize memory
Memory Management:
- Off-screen contact cards removed from DOM
- Selection state maintained in JavaScript object
- Avatar images lazy loaded when cards become visible
Scroll Position: Maintains scroll position during search operations
Loading States: Skeleton loading animation while fetching additional contact

Company Detail View - Business Rules

Back to Companies Button: Returns user to main companies list view
Page maintains filter state: Previous search/filter selections preserved when returning
Breadcrumb Navigation: Shows current location in application hierarchy

Company Information Display:

Company Name: Primary heading, pulled from companies.name field
Company Description: Subtitle text, pulled from companies.description field
Company Avatar: Circular avatar showing company initials (first letter of each word in company name)
Avatar Fallback: Generic building icon if company name unavailable

Contact Information Display:

Website URL: Clickable link, opens in new tab, validates URL format
Email Address: Clickable mailto link, validates email format
Phone Number: Formatted display, clickable tel link on mobile
Physical Address: Formatted as "City, State" from address fields
Employee Count: Formatted as "201-500 employees" from company_size field
Revenue Range: Formatted as "$50M - $100M" from annual_revenue field

Company Status and Metrics:

AI Score: Numeric display (0-100), calculated from engagement metrics
Status Badge: Visual indicator (Active, Inactive, Prospect) from status field
Industry Classification: Pulled from industry field with corresponding icon

Tags Display:

Tag Pills: Visual display of company tags
Tag Limit: Shows first 5 tags with "..." indicator for more
Add Tag Button: Opens tag management interface
Tag Removal: Individual "x" button on each tag for authorized users

Quick Actions Panel Rules

Primary Actions:

Edit Company Button: Opens edit modal with current company data pre-populated
Access Control: Only available to users with company edit permissions
Validation: Checks if company is locked by another user

Communication Actions:

Email Button: Opens email composition interface
Call Button: Opens call interface with contact selection
Access Control: Available to users with communication permissions

Relationship Management:

Add Contact Button: Opens contact attachment interface
Contact Validation: Shows only unattached contacts for this company

Research Update: Will be implemented in Phase 2
Create RFP: Separate ticket - not included in current scope
Add Deal: Will be implemented in Phase 2
Add Note: Opens note creation interface

System Aging & Technology Maturity Section Rules

Overall Assessment Display:

Overall Maturity Field: Dropdown selection (Modern, Advanced, Standard, Legacy)
Maturity Score: Percentage field (0-100%)
Score Calculation: Weighted average of all system component scores
Edit Access: Available to users with system assessment permissions

Systems & Tools Configuration:

CRM System Field: Text field showing current CRM platform
Marketing Tools Field: Text field showing marketing platform
Analytics Platform Field: Text field showing analytics solution
Field Validation: Free text entry with suggested values

Technical Configuration:

Data Integration Method: Dropdown (API-First, File-Based, Manual, None)
Automation Level: Dropdown (High, Medium, Low, None)
Process Classification: Based on automation level selection

Maturity Score Calculation Formula:

Overall Maturity Score = (
  (CRM_System_Score * 0.25) +
  (Marketing_Tools_Score * 0.25) +
  (Analytics_Platform_Score * 0.20) +
  (Data_Integration_Score * 0.15) +
  (Automation_Level_Score * 0.15)
)

Where individual scores are:
- Modern/High = 100 points
- Advanced/Medium = 75 points  
- Standard/Low = 50 points
- Legacy/None = 25 points

Edit System Aging Modal Rules:

Tab Display:

Active Tab Indication: Visual highlighting of current selected tab
Tab Count Indicators: Dynamic counts where applicable
Access Control: Tabs hidden if user lacks permissions

Tab Definitions:

Contacts Tab: Shows company-associated contacts with count
Research Tab: Will be implemented in Phase 2
RFPs Tab: Separate ticket - not included in current scope
Deals Tab: Will be implemented in Phase 2
AI Insights Tab: Will be implemented in Phase 2
Notes Tab: Shows company notes with functionality
Activities Tab: Shows company activity timeline

Company Contacts Section Rules

Contact List Display:

Section Title: "Company Contacts" with dynamic count in parentheses
Contact Count Calculation: COUNT(*) from contact_company_relationships table
Empty State: Shows "No contacts associated" when count = 0

Add Contact Button:

Button Text: "Add Contact" with plus icon
Click Action: Opens contact attachment modal
Availability: Only shown to users with contact management permissions

Contact Table Structure:

Contact Column: Avatar + Name + Email display
Position Column: Job title from contact record
Score Column: Contact engagement score (0-100)
Status Column: Lead status badge (Hot Lead, Qualified, Nurturing)
Contact Info Column: Email + Phone formatted display
Tags Column: Contact-specific tags
Last Contact Column: Last interaction timestamp
Actions Column: Three-dot menu with contact actions

Contact Data Rules:

Contact Avatar: Initials-based circular avatar
Contact Name: Linked to contact detail page
Email Display: Clickable mailto link
Phone Display: Formatted phone number
Score Display: Numeric score with visual indicator
Status Badge: Styled based on lead_status field
Last Contact: Relative time display (e.g., "2 days ago")

View Contact: Navigate to contact detail page
Edit Contact: Open contact edit modal
Remove from Company: Unlink contact from company (with confirmation)
Send Email: Open email composition for specific contact
Schedule Call: Open call scheduling interface

Email Functionality Rules

Email Recipient Selection:

Recipient Display Format:

Company Entry: Company name + email with building icon
Contact Entries: Contact name + email + job title
Avatar Display: Initials-based avatars for each entry
Selection State: Checkbox indication for each recipient

Email Composition Rules:

Template Selection: Pre-built email templates
Available Templates:
- Company Introduction: Partnership opportunity template
- Follow-up: Follow-up on discussion template
- Product Demo Request: Product demo template
Custom Option: Free-form email composition
Template Preview: Preview button shows template content

Custom Email Fields:

Subject Line: Text input field with placeholder
Email Content: Rich text area with formatting options
Character Limits: Subject line max 150 characters
Content Validation: Required field validation

Email Actions:

Preview Button: Shows email preview before sending
Send Button: Dynamic text based on recipient count
Back Navigation: Return to recipient selection

Call Functionality Rules

Contact Selection for Calls:

Call Purpose Selection:

Call Execution Interface:

Call Documentation Fields:

Call Status: Dropdown (Completed, No Answer, Busy, Rescheduled)
Call Date: Date picker defaulting to current date
Call Time: Time picker with duration tracking
Notes: Multi-line text area for call summary and next steps
Character Limit: Notes field max 1000 characters

Call Script Content:

Dynamic Content: Script varies based on selected call purpose
Personalization: Company name and contact name inserted into script
Talking Points: Bullet-pointed suggestions for conversation flow

Quick Tips Checklist:

Interactive Checkboxes: Tips can be checked off during call
Standard Tips: Listen more than speak, ask open-ended questions, take detailed notes, identify pain points
Purpose-Specific Tips: Additional tips based on call purpose selection

Notes Section Rules

Notes Display:

Section Title: "Company Notes"
Empty State: Placeholder text when no notes exist
Note Input: Multi-line text area with placeholder text
Add Note Button: Saves note and clears input field

Note Input Rules:

Placeholder Text: "Add a new note about this company... (Ctrl+Enter to save)"
Character Limit: 1000 characters maximum
Auto-Resize: Text area expands as content increases
Keyboard Shortcut: Ctrl+Enter saves note

Note Creation Rules:

Auto-Timestamp: Current date/time assigned to new notes
User Assignment: Current user assigned as note author
Company Association: Note linked to current company ID
Validation: Cannot save empty notes

Note Display Rules:

Chronological Order: Most recent notes displayed first
Note Metadata: Author name and timestamp shown
Note Content: Full note text displayed
Edit Access: Note authors can edit their own notes
Delete Access: Note authors and admins can delete notes

Activities Section Rules

Activity Timeline:

Section Title: "Company Activities"
Add Activity Button: Opens activity creation interface
Chronological Display: Most recent activities first
Activity Types: Meeting, Call, Email, Demo, Proposal, etc.

Activity Display Format:

Activity Icon: Type-specific icon for each activity
Activity Title: Brief description of activity
Date/Time Stamp: When activity occurred
Duration: Length of activity where applicable
Participants: People involved in activity
Description: Detailed activity notes
Attachments: Files associated with activity
Outcome Status: Result or next steps

Activity Creation Rules:

Activity Type: Required dropdown selection
Activity Date: Required date/time picker
Duration: Optional time duration field
Participants: Multi-select contact picker
Description: Required text area for activity details
Attachments: Optional file upload capability
Outcome: Optional outcome/next steps field

Activity Data Validation:

Activity Type: Must be from predefined list
Date/Time: Cannot be in future (except for scheduled activities)
Participants: Must be valid contacts in system
Description: Required field, minimum 10 characters
File Attachments: Validate file type and size limits

Data Access and Security Rules

View-Level Permissions:

Company View Access: User must have read permissions for company
Contact Information: Contact details based on user's contact permissions
System Maturity: Technical information requires system access role
Edit Capabilities: Modify permissions checked for each editable element

Data Loading Rules:

Company Data: Loaded from companies table by company_id
Contact Relationships: Joined from contact_company_relationships
System Maturity: Loaded from company_system_maturity table
Activity History: Loaded from company_activities table
Notes: Loaded from company_notes table

Real-Time Updates:

Contact Count: Updates when contacts added/removed
Activity Timeline: Updates when new activities added
Notes Section: Updates when notes added/edited
System Maturity: Updates when assessments modified

Error Handling:

Company Not Found: Redirect to companies list with error message
Permission Denied: Show access denied message with support contact
Data Loading Errors: Show retry option with error details
Network Issues: Offline indicator with retry capability

Integration Rules

CRM System Integration:

Data Synchronization: Company updates sync to external CRM
Contact Management: Contact changes reflected in CRM
Activity Logging: Activities logged to external systems
Conflict Resolution: External system takes precedence for conflicts

Email Integration:

Email Tracking: Sent emails logged to activity timeline
Template Management: Email templates stored in template system
Delivery Confirmation: Email delivery status tracked
Reply Integration: Replies linked to company record

Audit Trail:

View Tracking: Company page views logged for analytics
Edit History: All modifications tracked with user/timestamp
Access Logging: Failed permission checks logged
Data Changes: Before/after values stored for rollback capability

Real-time Updates and Sync Rules

Data Refresh: Company list auto-refreshes every 5 minutes for status and score updates
Conflict Resolution: If record modified by another user, shows notification with option to refresh

8. Sample Data

Company Records

TechCorp Solutions
- Industry: Technology
- Size: 201-500 employees  
- Revenue: $50M - $100M
- Location: San Francisco, CA
- Website: www.techcorp.com
- Status: Active
- AI Score: 94
- Tags: Enterprise, SaaS, High Value

Financial Services Group
- Industry: Finance
- Size: 201-500 employees
- Revenue: $150M
- Location: Boston, MA  
- Status: Inactive
- Score: 55
- Tags: Banking, Investment, Insurance

Global Manufacturing Co.
- Industry: Manufacturing
- Size: 201-500 employees
- Revenue: $200M
- Location: Chicago, IL
- Status: Active
- Score: 92
- Tags: Industrial, Supply Chain, Automation

Contact Information

Sarah Johnson (TechCorp Solutions)
- Position: VP of Sales
- Email: sarah.johnson@techcorp.com
- Phone: +1 (555) 123-4567
- Score: 95
- Status: Hot Lead
- Tags: Enterprise, Decision Maker

Robert Chen (TechCorp Solutions)  
- Position: CTO
- Email: robert.chen@techcorp.com
- Phone: +1 (555) 123-4568
- Score: 88
- Status: Qualified
- Tags: Tech, Decision Maker

Maria Rodriguez (TechCorp Solutions)
- Position: Product Manager
- Email: maria.rodriguez@techcorp.com
- Phone: +1 (555) 123-4569
- Score: 82
- Status: Nurturing
- Tags: Product, Influencer

Technology Assessment

Overall Maturity: Modern (85%)
CRM System: Salesforce (Advanced)
Marketing Tools: HubSpot (Integrated)
Analytics Platform: Custom Dashboard
Data Integration: API-First
Automation Level: High

Deal Pipeline

Enterprise Software License
- Value: $250,000
- Probability: 75%
- Status: Proposal
- Close Date: 2024-02-15
- Owner: John Smith
- Contacts: 0

Professional Services
- Value: $50,000  
- Probability: 85%
- Status: Negotiation
- Close Date: 2024-01-30
- Owner: Sarah Johnson

Annual Maintenance
- Value: $25,000
- Probability: 100%
- Status: Closed Won
- Close Date: 2024-01-10
- Owner: Mike Chen

RFP Sample

Enterprise Software Platform RFP
- Budget: $500K - $1M
- Issue Date: 2024-01-15
- Due Date: 2024-02-15
- Briefing Date: 2024-01-22
- Submission Date: 2024-02-10
- Status: In Progress
- Champion: Robert Chen
- Decision Makers: 1 assigned
- Sections: 4 (Technical Requirements, Pricing & Commercial Terms, Implementation Timeline, Support & Maintenance)
- Competition: 3 competitors
- Win Probability: 75%

9. Acceptance Criteria

The system must allow users to create new companies with required fields (name, email) and optional fields (website, phone, industry, size, revenue, address, description).
The system must provide a searchable company list with filtering capabilities by status, industry, and other attributes.
The system must display company metrics on the dashboard including total companies, at-risk companies, open opportunities, and companies with no recent activity.
The system must allow users to associate existing contacts with companies through a search and selection interface.
The system must support bulk company creation through CSV import with data validation and error reporting.
The system must provide a comprehensive company profile page showing basic information, contacts, deals, RFPs, activities, and technology assessment.
The system must allow editing of company information through modal forms with field validation.
The system must support contact management including adding new contacts, searching existing contacts, and managing contact relationships.
The system must provide integrated email functionality with recipient selection, template options, and custom message composition.
The system must support RFP creation with multi-step workflow including basic info, stakeholders, sections, and analysis components.
The system must allow technology maturity assessment with scoring for overall maturity, systems, tools, and technical configuration.
The system must provide deal and opportunity management with pipeline tracking, value calculations, and probability assessment.
The system must support activity logging including meetings, emails, calls, and other engagement types with participant tracking.
The system must provide quick actions panel for common tasks (edit company, email, call, add contact, add deal, add note).
The system must calculate and display company scores based on engagement, technology maturity, and other factors.
The system must support stakeholder management in RFPs with role assignment and influence level tracking.
The system must provide competitive analysis features including competitor tracking and win-loss analysis.
The system must support document attachment and management for activities, RFPs, and company records.
The system must provide export functionality for company data in CSV format with user permission validation.
The system must maintain audit trails for all data changes with timestamp and user tracking.

10. Process Changes

Process AreaFromToImpactCompany Data EntryManual entry across multiple systems with 60% data duplicationCentralized single-entry system with automated validation75% reduction in data entry timeContact ManagementSpreadsheet tracking with manual updates and inconsistent formattingIntegrated contact database with automated relationship mapping50% improvement in contact data accuracyOpportunity TrackingEmail-based deal tracking with manual status updatesAutomated pipeline management with real-time probability scoring40% improvement in forecast accuracyRFP ManagementDocument-based RFP creation with manual stakeholder coordinationStructured RFP workflow with automated notifications and tracking60% reduction in RFP response timeTechnology AssessmentManual questionnaires with inconsistent scoring methodsStandardized digital assessment framework with comparative analytics80% improvement in assessment consistencyCommunication TrackingSeparate email systems with manual activity loggingIntegrated communication platform with automatic activity capture90% increase in communication visibilityCompetitive AnalysisAd-hoc analysis in isolated documentsSystematic competitive intelligence with historical trend analysis70% improvement in competitive insightsReporting and AnalyticsManual report generation from multiple data sourcesAutomated dashboards with real-time performance metrics85% reduction in reporting preparation time

Impact percentages are estimated based on typical CRM implementation results and process automation benefits. Actual results may vary based on user adoption and system utilization patterns.

11. Impact from Solving This Problem

Metric CategoryImprovement AreaImpact DescriptionSales EfficiencyDeal Cycle Time30% reduction in average sales cycle through better prospect qualification and streamlined communication workflowsData QualityInformation Accuracy85% improvement in data consistency across all company records through automated validation and single-source-of-truth architectureUser ProductivityAdministrative Tasks60% reduction in manual data entry and administrative overhead through automation and integrated workflowsRevenue PerformancePipeline Visibility45% improvement in forecast accuracy through real-time opportunity tracking and probability-based analyticsCustomer RelationshipsEngagement Quality50% increase in meaningful customer interactions through comprehensive relationship mapping and activity historyCompetitive PositioningWin Rate25% improvement in competitive win rate through systematic intelligence gathering and strategic positioning analysisProcess StandardizationWorkflow Consistency70% improvement in process adherence through guided workflows and automated validation rulesDecision MakingData-Driven Insights80% faster access to critical business intelligence through integrated dashboards and real-time analyticsCollaboration EfficiencyTeam Coordination55% improvement in cross-team information sharing through centralized data access and activity trackingCompliance and AuditDocumentation Standards90% improvement in audit trail completeness through automated activity logging and change tracking

Impact metrics are projected based on industry benchmarks for CRM system implementations. Actual results depend on user adoption rates, data quality at implementation, and organizational change management effectiveness.

12. User Behavior Tracking

Sales Manager Tracking Plan

Event CategorySpecific EventsProperties TrackedQuestions AnsweredDashboard UsageDashboard_View, Filter_Applied, Metric_Clickeduser_id, timestamp, filter_type, metric_name, session_durationHow often do managers review company metrics? Which filters are most valuable?Company AnalysisCompany_Profile_Viewed, Technology_Assessment_Accessed, Deal_Pipeline_Analyzedcompany_id, view_duration, sections_accessed, actions_takenWhich companies receive most management attention? What drives deep-dive analysis?Performance MonitoringTeam_Performance_Reviewed, Activity_Report_Generated, Forecast_Updatedteam_member_id, report_type, frequency, accuracy_metricsHow frequently do managers review team performance? Which reports drive decisions?Strategic PlanningExport_Data, Bulk_Actions, Priority_Changesdata_type, record_count, action_type, impact_scopeWhat data is needed for external analysis? How often do priorities shift?

Sales Representative Tracking Plan

Event CategorySpecific EventsProperties TrackedQuestions AnsweredData ManagementCompany_Created, Company_Edited, Bulk_Import, Contact_Addedcreation_method, field_completion_rate, time_to_complete, validation_errorsHow efficiently do reps manage company data? Where do data quality issues occur?Communication FlowEmail_Sent, Template_Used, Recipient_Selected, Follow_up_Scheduledtemplate_type, recipient_count, response_rate, engagement_scoreWhich communication methods are most effective? How well are follow-ups managed?Opportunity ManagementDeal_Created, Status_Updated, Probability_Changed, Close_Date_Modifieddeal_value, stage_progression, time_in_stage, win_loss_outcomeHow effectively do reps manage their pipeline? What predicts deal success?Activity TrackingMeeting_Logged, Activity_Created, Document_Attached, Note_Addedactivity_type, duration, participant_count, outcome_qualityWhat activities correlate with successful outcomes? How thoroughly are interactions documented?

Business Development Manager Tracking Plan

Event CategorySpecific EventsProperties TrackedQuestions AnsweredTechnology AssessmentAssessment_Updated, Maturity_Score_Changed, Integration_Evaluated, Competitive_Analysisassessment_category, score_change, evaluation_criteria, competitive_factorsHow accurately do we assess prospect readiness? Which factors predict integration success?RFP ManagementRFP_Created, Section_Added, Stakeholder_Assigned, Analysis_Completedrfp_complexity, stakeholder_count, completion_time, win_probabilityWhat RFP characteristics predict success? How well do we manage complex sales processes?Partnership DevelopmentPartnership_Opportunity_Identified, Competitive_Intelligence_Updated, Win_Loss_Analyzedpartnership_type, market_factors, competitive_landscape, outcome_factorsWhich partnership opportunities offer highest value? How does competitive positioning affect outcomes?Strategic AnalysisMarket_Research_Conducted, Industry_Trend_Analyzed, ROI_Calculated, Strategy_Developedresearch_depth, trend_impact, roi_metrics, strategy_effectivenessHow do market insights influence strategy? Which analyses drive business decisions?

Cross-Role Analytics

Metric CategoryKey QuestionsTracking ApproachSystem AdoptionWhich features drive user engagement and retention?Feature usage frequency, user session patterns, abandonment pointsProcess EfficiencyHow does system usage improve sales cycle time and win rates?Conversion funnel analysis, time-to-completion metrics, outcome correlationData Quality ImpactHow does data completeness affect sales performance?Data completeness scoring vs. outcome metrics, error rate trackingCollaboration PatternsHow effectively do teams share information and coordinate activities?Cross-user data access patterns, handoff efficiency, information flow analysis

Note: Phase 2 features (Research, Deal Details, AI Insights) will include additional tracking for advanced analytics usage, AI recommendation acceptance rates, and deep research workflow patterns.