Software Requirement Specification (SRS) - Contact Form & Message Management

General Information

Field	Detail
Company Name	ruizdev7
Document Title	Contact Form & Message Management - SRS
Document Number	SRS-004
Version	1.0
Specification Date	17-November-24
Status	Implemented

Document Approval

Role	Name	Date
Project Manager	Joseph Ruiz	17-November-24
Tech Lead	Joseph Ruiz	17-November-24

Revision History

Version	Date	Changes Made	Author
1.0	17-November-24	Initial SRS Documentation	Joseph Ruiz

1. Introduction

1.1 Purpose

This document specifies the requirements for the implementation of a Contact Form and Message Management System in the ruizdev7 Portfolio application.
The objective is to provide visitors with a user-friendly communication channel and administrators with tools to manage, track, and respond to incoming messages effectively.

1.2 Scope

The Contact Form & Message Management System includes the following components:

• Public Contact Form: Accessible to all visitors without authentication for submitting inquiries.
• Message Storage: Persistent storage of all contact submissions with metadata.
• Message Management: Administrative interface for viewing, filtering, and managing messages.
• Read Status Tracking: Mark messages as read/unread for follow-up management.
• Pagination Support: Efficient retrieval of large message volumes.
• Validation & Security: Input validation, XSS prevention, and spam protection.
• Email Notification: (Future) Automatic email notifications for new submissions.

The implementation ensures:

• Data privacy and secure message handling
• Prevention of spam and malicious submissions
• Efficient message retrieval for administrators
• User-friendly submission experience

1.3 Definitions

• Contact Message: A user-submitted inquiry containing name, email, subject, and message body.
• Read Status: Boolean indicator showing whether an administrator has reviewed a message.
• Pagination: Dividing message lists into pages for improved performance and usability.
• Validation: Client and server-side checks ensuring data integrity and security.
• XSS (Cross-Site Scripting): Security vulnerability prevented through input sanitization.

2. Functional Requirements

UC-027

Priority: High
Description:

Field	Detail
Use Case Name	Submit Contact Form
Subject Area	Communication
Business Event	This use case applies when a visitor wants to send a message through the contact form.
Actors	General visitor (no authentication required), ruizdev7 Platform.
Use Case Overview	This use case covers the submission and storage of contact form messages.
Preconditions	None (public endpoint).
Termination Outcome	Message is validated, stored in database, and confirmation is sent to visitor.
Condition Affecting Outcome	Validation errors, missing required fields, database errors, or spam detection.
Use Case Description	The system validates form inputs (name, email, subject, message), sanitizes data to prevent XSS, stores the message with timestamp, and returns success confirmation.
Use Case Associations	UC-028: View Contact Messages.
Traceability To	SRS-004.
Input Summary	Name (string, required), Email (valid email format, required), Subject (string, required), Message (text, required).
Output Summary	Success message: “Thank you for your message! I’ll get back to you soon.”
Usability Index	Critical, primary communication channel for visitors.
Use Case Notes	No authentication required. Consider implementing reCAPTCHA for spam prevention.

UC-028

Priority: High
Description:

Field	Detail
Use Case Name	View Contact Messages
Subject Area	Message Management
Business Event	This use case applies when administrators need to review submitted messages.
Actors	Authenticated administrator, ruizdev7 Platform.
Use Case Overview	This use case covers retrieving and displaying all contact messages with pagination.
Preconditions	User must be authenticated with valid JWT token.
Termination Outcome	Paginated list of messages is displayed with metadata (name, email, subject, timestamp, read status).
Condition Affecting Outcome	No messages available, authentication failure, or database errors.
Use Case Description	The system authenticates the user, retrieves messages from database ordered by creation date (newest first), applies pagination, and returns formatted results.
Use Case Associations	UC-027: Submit Contact Form, UC-029: Mark Message as Read.
Traceability To	SRS-004.
Input Summary	Page number (default: 1), Items per page (default: 10).
Output Summary	Array of messages with pagination metadata (total pages, current page, has_next, has_prev).
Usability Index	Critical for administrators.
Use Case Notes	Requires JWT authentication. Messages ordered by created_at DESC.

UC-029

Priority: Medium
Description:

Field	Detail
Use Case Name	Mark Message as Read
Subject Area	Message Management
Business Event	This use case applies when administrators review messages and want to mark them as processed.
Actors	Authenticated administrator, ruizdev7 Platform.
Use Case Overview	This use case covers updating the read status of contact messages.
Preconditions	Message must exist, user must be authenticated.
Termination Outcome	Message read status is updated to true.
Condition Affecting Outcome	Message not found, authentication failure, or database errors.
Use Case Description	The system authenticates the user, locates the message by ID, updates the read field to true, commits to database, and returns confirmation.
Use Case Associations	UC-028: View Contact Messages.
Traceability To	SRS-004.
Input Summary	Message ID (integer).
Output Summary	Confirmation message and updated message data.
Usability Index	Medium, helps track message follow-up.
Use Case Notes	Returns 404 if message not found. Consider adding “Mark as Unread” functionality.

UC-030

Priority: Low
Description:

Field	Detail
Use Case Name	Filter Contact Messages
Subject Area	Message Management
Business Event	This use case applies when administrators need to find specific messages.
Actors	Authenticated administrator, ruizdev7 Platform.
Use Case Overview	This use case covers filtering messages by read status, date range, or search terms.
Preconditions	User must be authenticated.
Termination Outcome	Filtered list of messages matching criteria is returned.
Condition Affecting Outcome	Invalid filter parameters or no matching results.
Use Case Description	The system applies filter criteria to the message query (read/unread, date range, keyword search) and returns matching results.
Use Case Associations	UC-028: View Contact Messages.
Traceability To	SRS-004.
Input Summary	Optional filters: read status (boolean), start date, end date, search keyword.
Output Summary	Filtered message list with pagination.
Usability Index	Low, convenience feature for large message volumes.
Use Case Notes	Future enhancement. Currently not implemented but recommended for scalability.

UC-031

Priority: Low
Description:

Field	Detail
Use Case Name	Delete Contact Message
Subject Area	Message Management
Business Event	This use case applies when administrators need to remove spam or irrelevant messages.
Actors	Authenticated administrator, ruizdev7 Platform.
Use Case Overview	This use case covers permanent deletion of contact messages.
Preconditions	Message must exist, user must be authenticated with appropriate permissions.
Termination Outcome	Message is permanently removed from database.
Condition Affecting Outcome	Message not found, authentication failure, or database errors.
Use Case Description	The system authenticates the user, verifies permissions, deletes the message record, and returns confirmation.
Use Case Associations	UC-028: View Contact Messages.
Traceability To	SRS-004.
Input Summary	Message ID.
Output Summary	Confirmation of deletion.
Usability Index	Low, primarily for spam management.
Use Case Notes	Future enhancement. Consider soft delete for audit purposes.

3. Acceptance Criteria

Criterion	Description / Acceptance Condition
Form Submission	Visitors can submit messages without authentication.
Input Validation	System validates all required fields and email format.
XSS Prevention	Input is sanitized to prevent cross-site scripting attacks.
Message Storage	All submissions are stored with timestamp and metadata.
Admin Access	Authenticated admins can view all messages with pagination.
Read Tracking	Admins can mark messages as read.
Response Time	Form submission processed in <500ms.
Pagination	Message list supports configurable pagination (default 10 per page).
Error Handling	Clear error messages for validation failures.
Success Feedback	Confirmation message displayed to users after submission.

4. Non-Functional Requirements

Category	Requirement
Performance	Form submission <500ms, message retrieval <300ms.
Security	Input validation, XSS prevention, CSRF protection, rate limiting.
Availability	99.9% uptime for contact form endpoint.
Scalability	Support for 10,000+ stored messages without performance degradation.
Usability	Intuitive form with clear labels and error messages.
Data Retention	Messages retained indefinitely unless manually deleted.
Privacy	Email addresses stored securely and not shared.

5. Technical Specifications

5.1 Database Schema

Table: tbl_contact_messages

• ccn_contact_message (Primary Key, Auto-increment)
• name (String, Max 100 chars, Required)
• email (String, Valid email format, Required)
• subject (String, Max 200 chars, Required)
• message (Text, Max 2000 chars, Required)
• read (Boolean, Default: False)
• created_at (Timestamp, Auto-generated)
• ip_address (String, Optional, for spam tracking)
• user_agent (String, Optional, for spam tracking)

5.2 API Endpoints

Method	Endpoint	Description	Auth	Permission
POST	/api/v1/contact	Submit contact form	No	None
GET	/api/v1/contact	Get messages (paginated)	Yes	JWT
PUT	/api/v1/contact/{id}/read	Mark message as read	Yes	JWT
DELETE	/api/v1/contact/{id}	Delete message (future)	Yes	JWT

5.3 Validation Rules

ContactFormSchema (Marshmallow):

• name: Required, String, 1-100 characters
• email: Required, Valid email format
• subject: Required, String, 1-200 characters
• message: Required, String, 1-2000 characters

Security Validations:

• Email regex validation
• HTML tag stripping to prevent XSS
• SQL injection prevention through ORM
• Rate limiting: Max 5 submissions per IP per hour (recommended)

5.4 Response Formats

Success Response (POST):

{
  "message": "Thank you for your message! I'll get back to you soon.",
  "status": "success"
}

Error Response:

{
  "error": "Validation error",
  "details": {
    "email": ["Not a valid email address."],
    "message": ["Field cannot be empty."]
  }
}

Messages List Response (GET):

{
  "messages": [
    {
      "ccn_contact_message": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "subject": "Inquiry about services",
      "message": "I would like to know more...",
      "read": false,
      "created_at": "2024-11-17T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 25,
    "pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

5.5 Frontend Components

Contact.jsx:

• Form with react-hook-form
• Validation with client-side checks
• Toast notifications for success/error
• Loading states during submission

ContactMessages.jsx:

• Admin panel for viewing messages
• Pagination controls
• Read/unread status indicators
• Mark as read functionality

5.6 Security Measures

1. Input Validation:

   • Client-side: React Hook Form validation
   • Server-side: Marshmallow schema validation

2. XSS Prevention:

   • HTML escaping in display
   • Input sanitization before storage

3. CSRF Protection:

   • Flask-WTF CSRF tokens
   • SameSite cookie attributes

4. Rate Limiting:

   • IP-based submission throttling
   • Exponential backoff for repeated failures

5. Spam Prevention:

   • Honeypot fields (hidden inputs)
   • Time-based submission validation
   • Consider: Google reCAPTCHA integration

5.7 Email Notification (Future)

Planned Features:

• Send email to admin on new submission
• Auto-reply to submitter confirming receipt
• Email template system
• Integration with SendGrid or AWS SES

Additional Information

Field	Detail
Stakeholders	ruizdev7 Team, Portfolio Visitors
Attachments	[API_DOCUMENTATION.md]
Tech Stack	Flask, SQLAlchemy, Marshmallow, React Hook Form
Frontend Components	Contact.jsx, ContactMessages.jsx
Future Enhancements	Email notifications, reCAPTCHA, advanced filtering

Final Approval

Name/Title	Signature	Date
Client Representative	ruizdev7	17-November-24
Company Representative	ruizdev7	17-November-24