# Product Requirements Document

## Validation Checklist

- [x] All required sections are complete
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Problem statement is specific and measurable
- [x] Problem is validated by evidence (business decision)
- [x] Context → Problem → Solution flow makes sense
- [x] Every persona has at least one user journey
- [x] All MoSCoW categories addressed (Must/Should/Could/Won't)
- [x] Every feature has testable acceptance criteria
- [x] Every metric has corresponding tracking events
- [x] No feature redundancy (check for duplicates)
- [x] No contradictions between sections
- [x] No technical implementation details included
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision
**Safely remove the discontinued Text Message Marketing system from BuyerKiosk while preserving all other SMS functionality and maintaining system stability.**

### Problem Statement
BuyerKiosk currently contains a comprehensive Text Message Marketing system (SellerMarketing) that includes Text Blast campaigns and trigger-based automated messaging. This system has been **discontinued as a business function** and is no longer supported or used. The presence of this deprecated code:
- Creates maintenance burden when updating related systems
- Confuses users who see inactive features in the UI
- Poses potential security risk from unmaintained code
- Consumes server resources via scheduled background processes
- Clutters the codebase making development harder

### Value Proposition
By cleanly removing the deprecated Text Marketing system, we will:
- **Reduce codebase complexity** - fewer files to maintain
- **Improve developer velocity** - less confusion about what code is active
- **Eliminate user confusion** - no more defunct menu items
- **Stop unnecessary processing** - background jobs no longer running
- **Maintain system integrity** - preserve all functional SMS features (transactional, two-way chat)

## User Personas

### Primary Persona: Store Administrator
- **Demographics:** Store owners/managers who use the BuyerKiosk admin interface daily
- **Goals:** Manage their store operations efficiently without distractions from unused features
- **Pain Points:** Currently sees "Seller Marketing" or "Smart Messaging" menu items that lead to defunct features; confusion about what tools are available

### Secondary Persona: BuyerKiosk Developer
- **Demographics:** Internal development team maintaining the platform
- **Goals:** Understand the codebase quickly, make changes confidently, avoid breaking working features
- **Pain Points:** The SellerMarketing namespace adds cognitive load; must determine which SMS features are active vs deprecated when working on related areas

## User Journey Maps

### Primary User Journey: Clean Admin Experience
1. **Current State (Before):** Admin logs in → sees "Seller Marketing" or "Smart Messaging" in sidebar → clicks it → finds unusable/confusing interface → frustrated
2. **Target State (After):** Admin logs in → sidebar shows only functional features → no confusion → productive workflow

### Secondary User Journey: Developer Maintenance
1. **Current State (Before):** Developer needs to modify SMS → must understand SellerMarketing vs Chat vs SMS namespaces → confusion about what's active → slower development
2. **Target State (After):** Developer needs to modify SMS → only active SMS systems exist → clear code paths → faster development

## Feature Requirements

### Must Have Features

#### Feature 1: Remove SellerMarketing UI
- **User Story:** As a store administrator, I want the admin interface to only show active features so that I don't get confused by deprecated tools.
- **Acceptance Criteria:**
  - [ ] "Seller Marketing" or "Smart Messaging" removed from sidebar navigation
  - [ ] All SellerMarketing page routes return 404 or redirect appropriately
  - [ ] No orphaned links remain in the admin interface
  - [ ] Login/logout flows unchanged

#### Feature 2: Remove SellerMarketing Backend Processing
- **User Story:** As a system administrator, I want deprecated background processes stopped so that server resources aren't wasted.
- **Acceptance Criteria:**
  - [ ] Trigger processing cron jobs disabled
  - [ ] SMS queue workers for marketing messages stopped
  - [ ] No errors in logs from missing components
  - [ ] System health monitoring unaffected

#### Feature 3: Preserve Event System Integrity
- **User Story:** As a store administrator, I want the Event Management system to continue working without the SMS trigger integration that was deprecated.
- **Acceptance Criteria:**
  - [ ] Event creation/editing works normally
  - [ ] Non-SMS event triggers (if any) continue functioning
  - [ ] Event reporting excludes SMS marketing data gracefully
  - [ ] No foreign key constraint errors

### Should Have Features

#### Feature 4: Database Cleanup Strategy
- **User Story:** As a database administrator, I want a clear plan for what happens to marketing data so that database integrity is maintained.
- **Acceptance Criteria:**
  - [ ] Decision made: Archive tables, drop tables, or leave for future cleanup
  - [ ] No foreign key violations from removal
  - [ ] Migration scripts created if tables are modified
  - [ ] Customer opt-in/opt-out data preserved (if used elsewhere)

#### Feature 5: Preserve Transactional SMS
- **User Story:** As a store administrator, I want appointment reminders and order notifications to continue working so that customers stay informed.
- **Acceptance Criteria:**
  - [ ] All existing transactional SMS sending unaffected
  - [ ] BuySMSController continues functioning
  - [ ] TextMessageService continues functioning
  - [ ] Twilio/Vonage integration intact

### Could Have Features

#### Feature 6: Code Cleanup Documentation
- **User Story:** As a developer, I want documentation of what was removed so that future developers understand the codebase history.
- **Acceptance Criteria:**
  - [ ] List of removed files/routes documented
  - [ ] Database tables affected documented
  - [ ] Reason for deprecation recorded

### Won't Have (This Phase)

- **Customer data migration** - We will NOT migrate marketing messages or blast history to another system
- **SMS marketing replacement** - We will NOT implement a replacement marketing system
- **External notification** - We will NOT notify customers about the feature removal (internal change only)
- **Partial removal** - We will NOT keep any part of the marketing system active "just in case"

## Detailed Feature Specifications

### Feature: Remove SellerMarketing UI and Backend

**Description:** Complete removal of the SellerMarketing module including UI routes, API endpoints, controllers, models, templates, JavaScript, and background workers.

**User Flow:**
1. Developer runs removal migration/script
2. System updates navigation menus
3. Routes return 404 for old marketing URLs
4. Background processes gracefully skip marketing tasks
5. Existing SMS functionality continues working

**Business Rules:**
- Rule 1: All SellerMarketing routes must be inaccessible (404 or redirect)
- Rule 2: No PHP errors should occur from missing classes
- Rule 3: Database foreign key constraints must not break
- Rule 4: Transactional SMS (BuyerKiosk\SMS\*) must continue working
- Rule 5: Two-way SMS Chat (BuyerKiosk\Chat\*) must continue working
- Rule 6: Staff Chat (BuyerKiosk\StaffChat\*) must continue working

**Edge Cases:**
- Scenario 1: User bookmarked marketing page → Expected: 404 page or redirect to dashboard
- Scenario 2: Scheduled blast still pending in database → Expected: Background job skips or fails gracefully
- Scenario 3: External link to marketing API → Expected: 404 response with clear error message
- Scenario 4: Event with SMS trigger configured → Expected: Trigger gracefully ignored or event updated

## Success Metrics

### Key Performance Indicators

- **Completion:** 100% of SellerMarketing code removed or disabled
- **Stability:** Zero production errors related to removal within 7 days post-deployment
- **Preservation:** 100% of transactional SMS continues working (verified by test messages)
- **Performance:** No degradation in system response times

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| marketing_route_404 | route_path, user_id | Track if users hit removed routes |
| transactional_sms_sent | type, store_id | Verify transactional SMS still works |
| background_job_skip | job_name, reason | Track graceful handling of deprecated jobs |

---

## Constraints and Assumptions

### Constraints
- Must not break production during deployment
- Must preserve all customer data (even if tables are deprecated)
- Must maintain transactional SMS functionality (critical business feature)
- Must not require customer notification or training
- Development time should be minimal (cleanup task, not new feature)

### Assumptions
- No stores are actively using the Text Marketing features
- Customer opt-in/opt-out preferences are NOT solely stored in marketing tables
- Twilio/Vonage webhook URLs are shared with transactional SMS (must preserve)
- Event Management system has no hard dependency on SMS triggers

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Breaking transactional SMS | High | Low | Thorough testing before deployment; staged rollout |
| Database foreign key violations | Medium | Medium | Review all FKs before removal; soft-delete first |
| Residual errors in logs | Low | High | Add graceful error handling for missing classes |
| Users confused by 404 pages | Low | Low | Add redirect to dashboard for old URLs |
| Two-way chat affected | High | Low | Chat is in separate namespace; verify isolation |

## Open Questions

- [x] ~~What to do with database tables?~~ **Decision needed during SDD phase**
- [x] ~~Are there external integrations depending on marketing APIs?~~ **None identified**
- [x] ~~Is customer opt-in data used elsewhere?~~ **To verify during SDD**

---

## Supporting Research

### Competitive Analysis
N/A - This is a deprecation/removal task, not a new feature.

### User Research
- Business decision: Text Marketing was discontinued due to low adoption and maintenance costs
- No user complaints expected as features were not actively used

### Market Data
N/A - Internal cleanup task.

---

## Components Identified for Removal

### Backend (PHP)
- `userfrosting/src/BuyerKiosk/SellerMarketing/` - Entire namespace (8+ classes)
- `userfrosting/routes/groups/sellermarketing.php` - API routes
- `userfrosting/routes/sellermarketing-ui.php` - UI routes
- `userfrosting/src/BuyerKiosk/TaskEngine/Jobs/SmsQueueJob.php` - Task engine job
- `userfrosting/src/BuyerKiosk/Mock/Generators/SellerMarketingMockGenerator.php` - Mock data

### Frontend
- `userfrosting/templates/themes/default/sellermarketing/` - All templates
- `userfrosting/templates/themes/default/loyalty/text-blast.html` - Legacy template
- `public_html/plugins/sellermarketing/` - JavaScript
- Sidebar menu items referencing marketing

### Background Processing
- `tasker/process-sms-triggers.php`
- `tasker/process-triggers.php`
- `tasker/process-sms-queue.php`
- `tasker/queue-pusher.php`
- `userfrosting/workers/sms-queue-worker.php`
- `userfrosting/scripts/run-sms-queue.php`
- `userfrosting/scripts/test-delivery-tracking.php`

### Database Migrations
- 14 migration files in `userfrosting/migrations/input/` related to seller_marketing

### Event Management Integration
- `userfrosting/src/BuyerKiosk/EventManagement/Adapters/SmsAdapter.php`
- FK constraints in `20251210_008_sms_blast_event_fk.json` and `20251210_009_sms_trigger_event_fk.json`

### Components to PRESERVE
- `userfrosting/src/BuyerKiosk/SMS/` - Transactional SMS (Twilio/Vonage integration)
- `userfrosting/src/BuyerKiosk/Chat/` - Two-way SMS chat
- `userfrosting/src/BuyerKiosk/StaffChat/` - Internal staff chat
- All webhook handlers for delivery tracking (used by both marketing and transactional)