https://github.com/frievoe97/whatsapp-dashboard
A React application that visually represents WhatsApp chats. Upload your .txt chat files and explore interactive plots—all processed locally without any data being uploaded to external servers.
https://github.com/frievoe97/whatsapp-dashboard
d3 d3-visualization d3js dashboard plot react reactjs typescript visualization whatsapp
Last synced: about 1 year ago
JSON representation
A React application that visually represents WhatsApp chats. Upload your .txt chat files and explore interactive plots—all processed locally without any data being uploaded to external servers.
- Host: GitHub
- URL: https://github.com/frievoe97/whatsapp-dashboard
- Owner: frievoe97
- License: other
- Created: 2024-10-13T18:28:56.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-02-07T22:12:26.000Z (over 1 year ago)
- Last Synced: 2025-02-07T22:27:47.812Z (over 1 year ago)
- Topics: d3, d3-visualization, d3js, dashboard, plot, react, reactjs, typescript, visualization, whatsapp
- Language: TypeScript
- Homepage: https://whatsapp-dashboard.friedrichvoelkers.de
- Size: 2.17 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# 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](https://chat-visualizer.de/)
## 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](https://nodejs.org/) 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](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](https://vitest.dev/) 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](https://www.npmjs.com/package/stopwords)). 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](https://www.npmjs.com/package/sentiment).
---
### 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](https://www.npmjs.com/package/sentiment) 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/`.
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](https://github.com/Pustur) for the [whatsapp-chat-parser](https://www.npmjs.com/package/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:
```
/-
```
### 🚀 Feature Branches
**When to use:** When developing a new feature.
**Format:** `feature/-`
**Example:** `feature/50-add-better-welcome-screen`
### 🛠️ Fix Branches
**When to use:** When fixing a bug or an issue.
**Format:** `fix/-`
**Example:** `fix/51-update-dependencies`
### 🔄 Refactor Branches
**When to use:** When improving existing code without adding new features.
**Format:** `refactor/-`
**Example:** `refactor/60-cleanup-auth-service`
### 📖 Docs Branches
**When to use:** When updating documentation files.
**Format:** `docs/-`
**Example:** `docs/72-update-api-readme`
### ✅ Test Branches
**When to use:** When adding or improving tests.
**Format:** `test/-`
**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](LICENSE.txt).