# FEATURE-SPECS.md - Sales CRM Mobile App
## Voice Assistant
| Feature | What It Does | Key Components | Success Criteria |
|---------|--------------|----------------|------------------|
| Floating Voice Button | Provides persistent voice command access across multiple app screens | - FloatingActionButton component
- Positioned bottom-right with 16dp margin
- Visible on: CallList, MessagesInbox, LeadProfile, TodaysPlays screens
- Toggle visibility based on screen context | Button appears consistently on designated screens; taps register with <100ms response |
| Tap-to-Talk Speech Recognition | Activates device microphone and processes speech input | - SpeechRecognizer API integration
- Visual feedback (pulsing animation)
- 10-second timeout with countdown indicator
- Error handling for no-speech/network issues | Speech capture initiates within 200ms; audio processing completes within 2 seconds |
| Command Parser | Interprets natural language commands into executable actions | - Keyword matching algorithm ("mark hot", "skip", etc.)
- Confidence scoring for ambiguous commands
- Fallback to confirmation dialog for low-confidence matches | 95% accuracy on predefined command phrases; ambiguous commands trigger clarification |
| Command Execution | Performs CRM actions based on parsed commands | - "Mark hot": Updates lead status via PATCH /api/leads/{id}
- "Skip": Moves lead to tomorrow's call list
- "Callback tomorrow": Sets callback date
- "Send follow-up": Triggers email template
- "Add note": Opens note modal with transcribed text | All commands execute appropriate API calls; UI updates reflect changes within 1 second |
## Call List
| Feature | What It Does | Key Components | Success Criteria |
|---------|--------------|----------------|------------------|
| Today's Call Queue | Displays prioritized leads scheduled for calls today | - GET /api/leads/call-list-today
- Priority sort: hot > warm > cold > follow-up date
- Pull-to-refresh synchronization
- Empty state with "No calls scheduled" | List loads within 2 seconds; sorting follows priority rules exactly |
| One-Tap VoIP Dialing | Initiates phone calls through VoIP integration | - VoIP SDK initialization on app start
- Tap handler on lead cards
- Call permission checks
- Dialer UI with call duration timer | Calls connect within 5 seconds; call events log to analytics |
| Call Status Updates | Records call outcomes and updates lead status | - Post-call modal with outcomes: Connected, Voicemail, No Answer, Wrong Number
- PATCH /api/calls/{id} with duration and outcome
- Automatic callback scheduling for missed calls | Status updates persist immediately; lead priority adjusts based on outcomes |
| List Management | Allows manual reordering and removal | - Drag handles for manual reprioritization
- Swipe-to-skip (moves to tomorrow)
- Undo snackbar for accidental actions | Manual sorts persist after app restart; skip actions update server within 1 second |
## Messages Inbox
| Feature | What It Does | Key Components | Success Criteria |
|---------|--------------|----------------|------------------|
| Collapsible Sections | Organizes messages by intent category | - ExpandableListView or SectionedRecyclerView
- Three sections: High Intent (red accent), Positive (amber), Other (gray)
- Persist collapsed state per session
- Unread count badges on section headers | Sections collapse/animate smoothly; state persists across app sessions |
| Conversation Cards | Displays message previews with contact info | - Card layout: Contact photo, name, message snippet, timestamp
- Unread indicator (blue dot)
- Tap target minimum 48dp
- Swipe actions: Archive, Mark Unread | Cards render without flicker; tap responses within 100ms |
| Chat Thread View | Shows full conversation history | - GET /api/messages/{leadId}
- Infinite scroll loading (20 messages per page)
- Message bubbles with timestamps
- Read receipts (double checkmarks) | Thread loads initial 20 messages within 1.5 seconds; scrolls smoothly at 60fps |
| SMS Composition | Sends new messages from chat thread | - Text input with character counter (160 chars)
- Send button (paper plane icon)
- POST /api/messages with leadId and content
- Optimistic UI update with temporary sending indicator | Messages send within 3 seconds; failed sends retry automatically once |
## Lead Profile
| Feature | What It Does | Key Components | Success Criteria |
|---------|--------------|----------------|------------------|
| Contact Information Panel | Displays lead details and company info | - Header: Name, company, title
- Contact chips: Phone (tap to call), Email (tap to email), Address (tap to maps)
- Edit button (pencil icon) opens form
- GET /api/leads/{id} with caching | Data loads within 1 second; contact actions launch appropriate apps |
| History Timeline | Shows chronological call and message activity | - Timeline UI with icons for call/email/SMS
- Grouped by date (Today, Yesterday, This Week, Older)
- Tap call entry to see duration and notes
- Tap message entry to open chat thread | Timeline renders without layout shifts; entries sorted newest-first |
| Status Badges | Visual indicators of lead temperature | - Badge components: Hot (red), Warm (orange), Cold (blue)
- Badge selector in toolbar
- PATCH /api/leads/{id}/status on change
- Confetti animation for "cold→hot" upgrades | Status changes reflect immediately; API calls complete within 800ms |
| Quick Actions Bar | Provides one-tap communication options | - Fixed bottom bar with 3 buttons: Call, Text, Email
- Call: Uses VoIP integration
- Text: Opens SMS composer pre-addressed
- Email: Launches email client with template | Actions trigger within 200ms; correct apps open with pre-filled data |
## Todays Plays
| Feature | What It Does | Key Components | Success Criteria |
|---------|--------------|----------------|------------------|
| AI-Generated Lead Recommendations | Displays top 3 leads to contact today | - GET /api/ai/recommendations (cached daily)
- Recommendation algorithm: engagement score + time since last contact
- Refresh button forces recalculation
- Explanation chip: "High engagement score" | Recommendations load within 2 seconds; different each day unless forced refresh |
| Pre-Written Message Suggestions | Provides context-aware message templates | - Three template buttons per lead
- Templates generated based on: lead status, last interaction, company type
- "Customize" option opens editor with template
- POST /api/ai/generate-message for custom requests | Templates appear instantly; send actions complete within 3 seconds |
| One-Tap Send | Delivers selected message via preferred channel | - Channel detection: SMS if mobile present, otherwise email
- Confirmation dialog shows message preview
- Send progress indicator
- Success toast with "Message sent to [Name]" | Messages deliver within 5 seconds; failure shows retry option |
| Performance Tracking | Records AI recommendation effectiveness | - Impression tracking for displayed recommendations
- Conversion tracking when leads become "hot"
- Weekly effectiveness report in settings
- A/B testing framework for algorithm versions | Analytics events fire reliably; reports show accurate conversion rates |
---
## Cross-Feature Requirements
- **Offline Support**: All features cache last API response; queue actions when offline
- **Error Handling**: Consistent toast messages for API failures with retry options
- **Loading States**: Skeleton screens for all data-fetching components
- **Permissions**: Graceful degradation when microphone/phone permissions denied
- **Sync**: Background sync every 15 minutes; manual sync via pull-to-refresh
## Testing Priorities
1. Voice command accuracy in noisy environments
2. VoIP call reliability across network conditions
3. Message sync consistency between devices
4. AI recommendation relevance scoring
5. Offline action queue processing
## Common Bug Patterns to Monitor
- Speech recognition timeout during long pauses
- List sorting inconsistencies after status changes
- Duplicate messages from rapid tapping
- Badge state mismatches after quick actions
- AI recommendations failing to refresh at midnight local time