System Requirements Document (SRD) for tidal-customer

1. Introduction

The tidal-customer project is a comprehensive Customer Churn Management System designed to predict customer churn and provide actionable insights to reduce it. This system leverages machine learning, advanced analytics, and an intuitive dashboard to help businesses retain customers effectively. The project is tailored for deployment on Vercel, ensuring scalability and ease of access.

This document outlines the system's requirements, functionalities, and design concepts to guide its development and implementation.

2. System Overview

The tidal-customer system is a data-driven solution aimed at identifying customers at risk of leaving a service and providing actionable strategies to retain them. The system will utilize a machine learning pipeline to analyze customer data, predict churn probability, and offer personalized retention strategies.

The system will consist of:

• A machine learning backend for churn prediction and insights.
• A RESTful API for seamless integration between the backend and frontend.
• An interactive dashboard for visualizing churn data, customer segmentation, and actionable insights.
• Advanced features such as explainability (SHAP/LIME), real-time predictions, and email alerts.

The system will be deployed on Vercel for fast, scalable, and reliable access.

3. Functional Requirements

• As a User, I should be able to input customer data and receive churn predictions.
• As a User, I should be able to view the churn probability and associated risk score (Low/Medium/High).
• As a User, I should be able to see feature importance explaining why a customer may churn.
• As a User, I should be able to view personalized retention strategies for high-risk customers.
• As a User, I should be able to visualize churn data through charts and graphs.
• As an Admin, I should be able to log in to access the dashboard.
• As an Admin, I should be able to receive email alerts for high-risk customers.
• As an Admin, I should be able to view real-time churn predictions.
• As a Developer, I should be able to deploy the system on Vercel with minimal configuration.

4. User Personas

4.1 Admin

• Role: Business decision-maker or analyst.
• Responsibilities: Monitor churn data, act on retention strategies, and manage customer engagement.
• Needs: Access to detailed insights, real-time predictions, and email alerts.

4.2 User

• Role: Customer service representative or marketing team member.
• Responsibilities: Analyze churn predictions and implement retention strategies.
• Needs: Easy-to-use interface for churn prediction and actionable insights.

5. Visuals Colors and Theme

The tidal-customer project will use a modern, professional color palette that reflects trust, reliability, and data-driven insights. The colors are designed to be visually appealing while maintaining clarity for data visualization.

• Background: #F8F9FA (Light Gray)
• Surface: #FFFFFF (White)
• Text: #212529 (Dark Charcoal)
• Accent: #007BFF (Bright Blue)
• Muted: #6C757D (Muted Gray)

This palette ensures a clean and professional look, with the bright blue accent drawing attention to key elements like buttons and charts.

6. Signature Design Concept

Interactive Data Universe

The homepage of the tidal-customer dashboard will feature an interactive data universe. Users will be greeted with a 3D rotating globe representing customer data points. Each data point will glow and pulse based on its churn risk level (green for low, yellow for medium, red for high).

Hovering over a data point will display a tooltip with quick stats (e.g., churn probability, risk score). Clicking on a data point will zoom into a detailed customer profile, showing churn insights and retention strategies.

Additional features:

• Smooth transitions: The globe rotates smoothly, and zoom animations are fluid.
• Dynamic color shifts: The background subtly changes from light blue to dark blue as the user interacts with the globe.
• Micro-interactions: Buttons and charts will have hover effects, with slight scaling and shadowing to enhance interactivity.

This design will make the dashboard visually stunning and engaging while maintaining its functionality.

7. Non-Functional Requirements

• Performance: The system should handle up to 1,000 concurrent users without performance degradation.
• Scalability: The system should be easily scalable to accommodate growing user bases.
• Security: Implement secure authentication for the admin dashboard.
• Usability: The dashboard should be intuitive and user-friendly.
• Availability: Ensure 99.9% uptime for the deployed system on Vercel.
• Maintainability: Code should be modular and well-documented for easy updates.

8. Tech Stack

Frontend

• React for Web

Backend

• Python
• FastAPI

Database

• MySQL (with Alembic for migrations)

AI Models

• GPT 5.4 for user-friendly responses
• SHAP for explainability

AI Tools

• Langchain
• Litellm for LLM Routing

Deployment

• Docker for local orchestration
• Vercel for serverless deployment

9. Assumptions and Constraints

Assumptions

• The system will primarily serve businesses in telecom, banking, and SaaS industries.
• Customer data will be provided in a structured format (e.g., CSV).
• Users will have basic technical knowledge to interact with the dashboard.

Constraints

• Deployment is limited to Vercel's free tier initially.
• The system must comply with data privacy regulations (e.g., GDPR).

10. Glossary

• Churn: The act of a customer leaving a service.
• EDA: Exploratory Data Analysis, a process of analyzing datasets to summarize their main characteristics.
• SHAP: SHapley Additive exPlanations, a method for explaining the output of machine learning models.
• LIME: Local Interpretable Model-agnostic Explanations, another method for model explainability.
• Risk Score: A classification of churn probability into Low, Medium, or High categories.
• Retention Strategy: Actions taken to retain customers and reduce churn.

This SRD provides a detailed blueprint for the **tidal-customer** project. Let me know if you'd like any further refinements or additional details!