Chat Visualizer

Overview

Chat Visualizer is a powerful, interactive web application built with React that lets you analyze and visualize your WhatsApp chat data in an intuitive and engaging way. Explore messaging patterns, sender statistics, sentiment trends, emoji usage, and more with ease. Plus, all data processing happens locally in your browser, ensuring your privacy and security.

Live Demo

Experience it live: Chat Visualizer

Features

• Interactive Visualizations: Dive into detailed data representations including messaging activity, sentiment trends, and more.
• Multi-language Support: Available in German, English, French, and Spanish.
• Local Data Processing: Your data never leaves your browser. Privacy guaranteed!
• Responsive Design: Enjoy a seamless experience on both mobile and desktop devices.
• Easy File Upload: Simply upload an exported WhatsApp .txt file to get started.

Getting Started

Prerequisites

Ensure you have Node.js installed.

Installation

1. Clone the repository:

git clone https://github.com/frievoe97/whatsapp-dashboard.git
cd whatsapp-dashboard

2. Install dependencies:

npm install

3. Run the development server:

npm run dev

Open your browser and navigate to http://localhost:5173 to view the app.

Building for Production

To build and run in host mode:

npm run dev -- --host

Testing

We use Vitest for testing. Tests ensure that plots render correctly and that file uploads and filtering work as expected. Tests run on every push, so you can be confident everything is working smoothly.

Note: Before pushing your changes, please run:

npx prettier --write .

to format the code according to our guidelines.

Plot Creation Guidelines

When creating a new plot, please consider the following:

• Container Setup:

  • Use a main container with ref={containerRef} to monitor size changes using useResizeObserver(containerRef).
  • Set a minimum and maximum height with overflow hidden, for example:

    style={{ minHeight: '350px', maxHeight: '550px', overflow: 'hidden' }}
    

  • Use responsive width classes (e.g., w-full md:min-w-[500px] md:basis-[500px]) to ensure proper display on mobile and desktop.

• Data Source:

  • The plot should utilize data from filteredMessages (stored in the global context) that holds the messages currently being displayed.

• Dark Mode Support:

  • Use the darkMode variable from the global context to adjust styles accordingly for dark or light themes.

Available Plots and Their Functionality

Below is an overview of the different plots available in the Chat Visualizer, along with a description of their functionality. For each plot, you can preview the appearance in both Dark Mode and Light Mode.

---

1. Aggregated Message Trends (AggregatePerTime)

Location: src/components/plots/AggregatePerTime.tsx
Description:
This plot displays the aggregated number of messages by hour, weekday, and month. It allows you to view data for each participant individually or as a combined total of all chat members. Additionally, you can toggle between absolute values and relative percentages.

---

2. Message Timeline (Timeline)

Location: src/components/plots/Timeline.tsx
Description:
This plot shows the number of messages over time. It allows you to choose whether to display values on a yearly or monthly basis. Data can be viewed for individual participants or as an aggregate for all members, and the values can be displayed as absolute numbers or percentages.

---

3. Participant Statistics Bar Chart (BarChartComp)

Location: src/components/plots/BarChartComp.tsx
Description:
This bar chart presents various statistics for each participant. The available metrics include:

• Number of Messages
• Average Words per Message
• Median Words per Message
• Total Words Sent
• Maximum Words in a Message
• Active Days
• Unique Words Count
• Average Characters per Message

Users can select the metric to display via a dropdown in the plot's title.

---

4. Top Emoji Usage (Emoji)

Location: src/components/plots/Emoji.tsx
Description:
This plot displays the top 10 most frequently used emojis across all chat participants.

---

5. Reply Network Diagram (ChordDiagram)

Location: src/components/plots/ChordDiagram.tsx
Description:
This diagram visualizes interactions between participants by showing who replies to whom and how often. A single click on a name filters the view to that individual, while a double-click resets the view to include all participants.

---

6. Common Word Usage (WordCount)

Location: src/components/plots/WordCount.tsx
Description:
This plot displays the top 10 most frequently used words for each participant, excluding common stopwords (using the stopwords npm package). It supports analyses in German, French, Spanish, and English (defaulting to English if the language is not identified).

---

7. Detailed Participant Stats (Stats)

Location: src/components/plots/Stats.tsx
Description:
This plot provides a comprehensive overview of various statistics for each participant, including:

• Number of Messages
• Average Words per Message
• Median Words per Message
• Total Words Sent
• Maximum Words in a Message
• Active Days
• Unique Words Count
• Average Characters per Message

---

8. Chat Sentiment Analysis (Sentiment)

Location: src/components/plots/Sentiment.tsx
Description:
This line chart visualizes the overall sentiment of the chat. It allows you to switch between a single aggregated sentiment line (combining positive and negative) and two separate lines for positive and negative sentiments. The chart shows a moving average, where the window is calculated as the number of days divided by 50. It supports German, French, English, and Spanish (defaulting to English) using AFINN and the sentiment npm package.

---

9. Sentiment Word Insights (SentimentWord)

Location: src/components/plots/SentimentWord.tsx
Description:
For each participant, this plot displays the top 10 "friendliest" and "least friendly" words based on sentiment analysis. It uses AFINN and the sentiment npm package and supports German, French, English, and Spanish (defaulting to English). A dropdown in the plot's title lets you toggle between the two lists.

---

10. Message Density Heatmap (HeatmapMonthWeekday)

Location: src/components/plots/HeatmapMonthWeekday.tsx
Description:
This heatmap compares the total number of messages across all participants. You can select different dimensions for both axes (choosing from 'Year', 'Month', 'Weekday', 'Hour', or 'Day') to customize the view.

Message Filtering Options

The Chat Visualizer offers a comprehensive set of filters that allow you to refine the messages used in the analysis. Use these filters to focus on specific time periods, participants, and more, ensuring that the visualizations reflect the data most relevant to you.

• Start Date and End Date:
  Specify the time period for the messages to be included in the analysis.

• Use Abbreviations / Use Full Names:
  Toggle between displaying abbreviated names or full names. This is particularly useful in group chats with many participants, helping to keep the visualizations clear.

• Select Weekdays:
  Choose which weekdays to include in the analysis, allowing you to observe trends on specific days.

• Select Senders:
  Choose which participants' messages should be included. The list shows both full names and their abbreviations (in parentheses), making it easier to identify each sender.

• Message Share (%):
  Set a threshold (default is 3%) indicating the minimum percentage of total messages a sender must contribute to be included in the analysis. Note that senders falling below this threshold cannot be manually reactivated via the "Select Senders" option.

Additionally, there are two buttons to control these filters:

• Apply:
  The filters are only applied when you press the "Apply" button.
• Reset:
  The "Reset" button clears the current filter selections. After resetting, you must press "Apply" again for the changes to take effect.

Contributing

This is my first proper open-source project, and I’m excited to see it evolve! Contributions, feedback, and feature requests are all welcome. Here's how you can contribute:

1. Fork the Repository: Click the "Fork" button on GitHub.
2. Create a Feature Branch: Follow the naming convention feature/<your-feature-name>.
3. Make Your Changes: Commit with clear and concise messages.
4. Open a Pull Request: Submit your PR and adhere to the contribution guidelines.

All changes are automatically tested and built via our CI workflows. Only merged PRs are pushed to master to maintain a stable codebase.

Acknowledgments

Special thanks to Pustur for the whatsapp-chat-parser npm package, which made parsing WhatsApp chats much easier! 🙏

Workflows

• Testing: Automated tests run on every push.
• Building: Build workflows are triggered after each merged PR.
• Branch Policy: Direct pushes to master are restricted; use feature branches and PRs.

Branch Naming Conventions

To maintain a clear and structured workflow, we follow a standardized naming convention for branches. Each branch name follows the format:

<type>/<issue-number>-<short-description>

🚀 Feature Branches

When to use: When developing a new feature.
Format: feature/<ISSUE-NUMBER>-<DESCRIPTION>
Example: feature/50-add-better-welcome-screen

🛠️ Fix Branches

When to use: When fixing a bug or an issue.
Format: fix/<ISSUE-NUMBER>-<DESCRIPTION>
Example: fix/51-update-dependencies

🔄 Refactor Branches

When to use: When improving existing code without adding new features.
Format: refactor/<ISSUE-NUMBER>-<DESCRIPTION>
Example: refactor/60-cleanup-auth-service

📖 Docs Branches

When to use: When updating documentation files.
Format: docs/<ISSUE-NUMBER>-<DESCRIPTION>
Example: docs/72-update-api-readme

✅ Test Branches

When to use: When adding or improving tests.
Format: test/<ISSUE-NUMBER>-<DESCRIPTION>
Example: test/85-add-user-service-tests

By following this convention, we ensure better organization, easier tracking, and a smoother development process.

Repo Activity

License

This project is licensed under the MIT License.