brand-master/CONTACT_MESSAGES_SYSTEM.md

Contact Messages Management System - Complete Guide

Overview

A complete Contact Messages management system for the Brand Master e-commerce platform that allows customers to submit contact forms and admins to manage messages from a dedicated dashboard.

Features

Public Contact Form

• Full name, email, phone (optional), subject, and message fields
• Frontend validation with error messages
• Required field indicators (red asterisks)
• Success confirmation after submission
• Enhanced user experience with placeholders and helpful hints

Admin Dashboard

• Dedicated "Contact Messages" tab in Admin panel
• Unread message counter badge
• Message listing table with:
  • Visual unread indicator (yellow highlight)
  • Status badges (New/Read/Replied)
  • Sortable by date
  • Filter by status
• Message details modal with:
  • Full message content display
  • Status update dropdown
  • Admin notes textarea
  • Delete functionality

Backend Features

• Full REST API for message management
• Admin-only endpoints with JWT authentication
• PostgreSQL database persistence
• Enhanced data model with:
  • Phone number support
  • Read/unread tracking
  • Status management (new/read/replied)
  • Admin notes capability

Database Schema

Table: contact_message
- id: INTEGER (Primary Key)
- full_name: VARCHAR (Customer name)
- email: VARCHAR (Customer email)
- phone: VARCHAR (Optional phone number)
- subject: VARCHAR (Message subject)
- message: TEXT (Message content)
- created_at: TIMESTAMP (Submission time)
- is_read: BOOLEAN (Read status, default: false)
- status: VARCHAR (new/read/replied, default: 'new')
- admin_notes: TEXT (Internal admin notes, nullable)

API Endpoints

Public Endpoint

POST /api/contact
Body: {
  "full_name": "John Doe",
  "email": "john@example.com",
  "phone": "+972 XX-XXX-XXXX",  // Optional
  "subject": "Product Inquiry",
  "message": "I have a question..."
}

Admin Endpoints (Requires Authentication)

GET /api/admin/contact-messages
Query Parameters:
  - status: (optional) Filter by status (new/read/replied)
  - is_read: (optional) Filter by read status (true/false)
  - skip: (optional) Pagination offset (default: 0)
  - limit: (optional) Page size (default: 100)

GET /api/admin/contact-messages/unread-count
Returns: { "unread_count": 5 }

GET /api/admin/contact-messages/{message_id}
Returns: Full message details

PUT /api/admin/contact-messages/{message_id}
Body: {
  "is_read": true,
  "status": "replied",
  "admin_notes": "Called customer and resolved issue"
}

DELETE /api/admin/contact-messages/{message_id}
Returns: { "message": "Contact message deleted successfully" }

Modified Files

Backend

1. backend/app/models/contact_message.py - Enhanced database model
2. backend/app/schemas/contact.py - Updated Pydantic schemas
3. backend/app/routers/contact.py - Added admin endpoints
4. backend/app/main.py - Registered admin router
5. backend/migrations/007_enhance_contact_messages.sql - Database migration

Frontend

1. frontend/src/pages/Contact.jsx - Enhanced form with validation
2. frontend/src/pages/Admin.jsx - Added Contact Messages management tab

Deployment Steps

Step 1: Apply Database Migration

# On Windows
cd c:\Users\dvirl\OneDrive\Desktop\gitea\brand-master
apply-migration.bat 007_enhance_contact_messages.sql

# Or on Linux/Mac
./apply-migration.sh 007_enhance_contact_messages.sql

Step 2: Build and Push Docker Images

# Build backend
cd backend
docker build -t harbor.dvirlabs.com/my-apps/brand-master-backend:latest .

# Build frontend
cd ../frontend
docker build -t harbor.dvirlabs.com/my-apps/brand-master-frontend:latest .

# Push to Harbor
docker push harbor.dvirlabs.com/my-apps/brand-master-backend:latest
docker push harbor.dvirlabs.com/my-apps/brand-master-frontend:latest

Step 3: Deploy to Kubernetes

cd brand-master-chart

# Upgrade Helm deployment
helm upgrade brand-master . \
  --namespace my-apps \
  --set backend.image.tag=latest \
  --set frontend.image.tag=latest \
  --wait

Step 4: Verify Deployment

# Check pods are running
kubectl get pods -n my-apps | grep brand-master

# Check backend logs
kubectl logs -n my-apps deployment/brand-master-backend --tail=50

# Check frontend logs
kubectl logs -n my-apps deployment/brand-master-frontend --tail=50

Testing

Test Public Contact Form

1. Navigate to https://brand-master.dvirlabs.com/contact
2. Fill in the form:
   • Full Name: Test User
   • Email: test@example.com
   • Phone: +972 50-123-4567 (optional)
   • Subject: Test Message
   • Message: This is a test message
3. Submit and verify success message

Test Admin Dashboard

1. Login as admin at https://brand-master.dvirlabs.com/login
2. Navigate to Admin Dashboard
3. Click "Contact Messages" tab
4. Verify:
   • ✅ Test message appears in list
   • ✅ Unread counter shows correct count
   • ✅ Message has yellow highlight (unread)
   • ✅ Status shows "NEW"
5. Click on message row to open details modal
6. Test actions:
   • Change status to "Read"
   • Add admin notes
   • Save changes
   • Verify message updated
   • Test delete functionality

Test Filters

1. Create messages with different statuses
2. Test status filter dropdown:
   • All Messages
   • New
   • Read
   • Replied
3. Verify filtering works correctly

Security Features

• Admin endpoints protected by JWT authentication
• Only users with is_admin=true can access admin endpoints
• Email validation on both frontend and backend
• SQL injection protection via SQLAlchemy ORM
• XSS protection via React's built-in escaping

Future Enhancements

• Email notifications for new messages
• Reply functionality from admin panel
• Attachment support
• Search functionality for messages
• Export messages to CSV
• Message templates for common responses
• Bulk actions (mark multiple as read, delete multiple)

Troubleshooting

Backend Issues

# Check backend logs
kubectl logs -n my-apps deployment/brand-master-backend --tail=100

# Common issues:
# 1. Migration not applied - Run migration script
# 2. Auth errors - Check JWT token and admin role
# 3. Database connection - Verify PostgreSQL is running

Frontend Issues

# Check frontend logs
kubectl logs -n my-apps deployment/brand-master-frontend --tail=100

# Common issues:
# 1. API calls failing - Check VITE_API_URL environment variable
# 2. Auth errors - Clear browser storage and re-login
# 3. Component errors - Check browser console

Database Issues

# Connect to PostgreSQL pod
kubectl exec -it -n my-apps deployment/brand-master-postgres -- psql -U brand_master -d brand_master_db

# Check if migration applied
\d contact_message

# View messages
SELECT id, full_name, email, subject, status, is_read, created_at FROM contact_message;

# Count unread messages
SELECT COUNT(*) FROM contact_message WHERE is_read = false;

Performance Considerations

• Messages are fetched only when admin clicks the "Contact Messages" tab
• Unread count is fetched once on admin dashboard load
• Table supports pagination (limit parameter)
• Indexes on status, is_read, and created_at for fast filtering
• Modal opens client-side without additional API calls

Maintenance

• Periodically review and archive old messages
• Monitor unread message count
• Review admin notes for customer service insights
• Consider data retention policies for GDPR compliance

---

Status: Ready for deployment Last Updated: 2026-05-08 Version: 1.0.0