{"id":25132903,"url":"https://github.com/frievoe97/whatsapp-dashboard","last_synced_at":"2025-04-23T22:23:01.257Z","repository":{"id":275208220,"uuid":"872083753","full_name":"frievoe97/whatsapp-dashboard","owner":"frievoe97","description":"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.","archived":false,"fork":false,"pushed_at":"2025-02-07T22:12:26.000Z","size":2276,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-07T22:27:47.812Z","etag":null,"topics":["d3","d3-visualization","d3js","dashboard","plot","react","reactjs","typescript","visualization","whatsapp"],"latest_commit_sha":null,"homepage":"https://whatsapp-dashboard.friedrichvoelkers.de","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frievoe97.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-13T18:28:56.000Z","updated_at":"2025-02-07T22:12:29.000Z","dependencies_parsed_at":"2025-02-07T22:23:44.907Z","dependency_job_id":null,"html_url":"https://github.com/frievoe97/whatsapp-dashboard","commit_stats":null,"previous_names":["frievoe97/whatsapp-dashboard"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frievoe97%2Fwhatsapp-dashboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frievoe97%2Fwhatsapp-dashboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frievoe97%2Fwhatsapp-dashboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frievoe97%2Fwhatsapp-dashboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frievoe97","download_url":"https://codeload.github.com/frievoe97/whatsapp-dashboard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237822689,"owners_count":19371850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["d3","d3-visualization","d3js","dashboard","plot","react","reactjs","typescript","visualization","whatsapp"],"created_at":"2025-02-08T15:18:53.444Z","updated_at":"2025-04-23T22:23:01.249Z","avatar_url":"https://github.com/frievoe97.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- Dark Mode GIF --\u003e\n\u003c!-- \u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/user-attachments/assets/e2b92304-8d8f-449a-98e3-925e0ce4a1cc#gh-dark-mode-only\" width=\"500\"\u003e\u003c/p\u003e --\u003e\n\n\u003c!-- Light Mode GIF --\u003e\n\u003c!-- \u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/user-attachments/assets/0aceb04f-1748-468f-aa07-cfa27ce6814f#gh-light-mode-only\" width=\"500\"\u003e\u003c/p\u003e --\u003e\n\n# Chat Visualizer\n\n![React](https://img.shields.io/badge/react-18.3.1-blue)\n![D3.js](https://img.shields.io/badge/d3-7.9.0-orange)\n![TypeScript](https://img.shields.io/badge/typescript-5.5.3-blue)\n![Vite](https://img.shields.io/badge/vite-5.4.8-purple)\n![ESLint](https://img.shields.io/badge/eslint-9.11.1-yellow)\n![TailwindCSS](https://img.shields.io/badge/tailwindcss-3.4.13-cyan)\n![whatsapp-chat-parser](https://img.shields.io/badge/whatsapp--chat--parser-4.0.2-green)\n![stopword](https://img.shields.io/badge/stopword-3.1.1-blue)\n![sentiment](https://img.shields.io/badge/sentiment-5.0.2-yellow)\n![emoji-regex](https://img.shields.io/badge/emoji--regex-10.4.0-purple)\n![franc-min](https://img.shields.io/badge/franc--min-6.2.0-orange)\n![lucide-react](https://img.shields.io/badge/lucide--react-0.474.0-cyan)\n![License](https://img.shields.io/badge/license-MIT-yellow)\n\n\u003c!-- Dark Mode Bild --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/b513738d-fdcf-4ffb-afbc-33cfcef338a2#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/66e2af2c-d577-4052-afee-5405a8dbfe0b#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n## Overview\n\n**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.\n\n## Live Demo\n\nExperience it live: [Chat Visualizer](https://chat-visualizer.de/)\n\n## Features\n\n- **Interactive Visualizations:** Dive into detailed data representations including messaging activity, sentiment trends, and more.\n- **Multi-language Support:** Available in German, English, French, and Spanish.\n- **Local Data Processing:** Your data never leaves your browser. Privacy guaranteed!\n- **Responsive Design:** Enjoy a seamless experience on both mobile and desktop devices.\n- **Easy File Upload:** Simply upload an exported WhatsApp `.txt` file to get started.\n\n## Getting Started\n\n### Prerequisites\n\nEnsure you have [Node.js](https://nodejs.org/) installed.\n\n### Installation\n\n1. Clone the repository:\n\n```\ngit clone https://github.com/frievoe97/whatsapp-dashboard.git\ncd whatsapp-dashboard\n```\n\n2. Install dependencies:\n\n```\nnpm install\n```\n\n3. Run the development server:\n\n```\nnpm run dev\n```\n\nOpen your browser and navigate to [http://localhost:5173](http://localhost:5173) to view the app.\n\n### Building for Production\n\nTo build and run in host mode:\n\n```\nnpm run dev -- --host\n```\n\n### Testing\n\nWe 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.\n\n\u003e **Note:** Before pushing your changes, please run:\n\n```\nnpx prettier --write .\n```\n\nto format the code according to our guidelines.\n\n## Plot Creation Guidelines\n\nWhen creating a new plot, please consider the following:\n\n- **Container Setup:**\n\n  - Use a main container with `ref={containerRef}` to monitor size changes using `useResizeObserver(containerRef)`.\n  - Set a minimum and maximum height with overflow hidden, for example:\n    ```\n    style={{ minHeight: '350px', maxHeight: '550px', overflow: 'hidden' }}\n    ```\n  - Use responsive width classes (e.g., `w-full md:min-w-[500px] md:basis-[500px]`) to ensure proper display on mobile and desktop.\n\n- **Data Source:**\n\n  - The plot should utilize data from `filteredMessages` (stored in the global context) that holds the messages currently being displayed.\n\n- **Dark Mode Support:**\n  - Use the `darkMode` variable from the global context to adjust styles accordingly for dark or light themes.\n\n## Available Plots and Their Functionality\n\nBelow 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.\n\n---\n\n### 1. Aggregated Message Trends (AggregatePerTime)\n\n**Location:** `src/components/plots/AggregatePerTime.tsx`  \n**Description:**  \nThis 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.\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/8b1b87b5-ed9c-4363-bedb-e3077a91b389#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/c9a7c88d-de21-481c-a196-a38405d1f418#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n### 2. Message Timeline (Timeline)\n\n**Location:** `src/components/plots/Timeline.tsx`  \n**Description:**  \nThis 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.\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/4d90f4f8-f072-40df-9d3b-8b1d3e43e475#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/cba4ddef-a22e-4c11-8e7c-2059087645ae#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n### 3. Participant Statistics Bar Chart (BarChartComp)\n\n**Location:** `src/components/plots/BarChartComp.tsx`  \n**Description:**  \nThis bar chart presents various statistics for each participant. The available metrics include:\n\n- Number of Messages\n- Average Words per Message\n- Median Words per Message\n- Total Words Sent\n- Maximum Words in a Message\n- Active Days\n- Unique Words Count\n- Average Characters per Message\n\nUsers can select the metric to display via a dropdown in the plot's title.\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/7890453e-f40b-4e5c-aa78-9ed72edb0c1c#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/df805b95-92ae-4e4d-96b8-03da82132512#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n### 4. Top Emoji Usage (Emoji)\n\n**Location:** `src/components/plots/Emoji.tsx`  \n**Description:**  \nThis plot displays the top 10 most frequently used emojis across all chat participants.\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/a21e4ada-fc43-4d38-9447-c9ca82bbdae2#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/4911da7a-397a-4aba-ba69-aa5353ad4c20#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n### 5. Reply Network Diagram (ChordDiagram)\n\n**Location:** `src/components/plots/ChordDiagram.tsx`  \n**Description:**  \nThis 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.\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/d9779aa6-74a2-476e-b542-bb809a00cfd0#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/da10b198-05ab-4d3b-8786-b9b678577bfe#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n### 6. Common Word Usage (WordCount)\n\n**Location:** `src/components/plots/WordCount.tsx`  \n**Description:**  \nThis 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).\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/0d123895-1245-4f1a-a87b-a59e528baa52#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/51a41615-6ea3-4240-a259-c063ca4321a4#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n### 7. Detailed Participant Stats (Stats)\n\n**Location:** `src/components/plots/Stats.tsx`  \n**Description:**  \nThis plot provides a comprehensive overview of various statistics for each participant, including:\n\n- Number of Messages\n- Average Words per Message\n- Median Words per Message\n- Total Words Sent\n- Maximum Words in a Message\n- Active Days\n- Unique Words Count\n- Average Characters per Message\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/e65a704f-9d30-4791-bb3b-eb942e3e3af1#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/5affc43d-fbcf-48b3-9566-15998c2e45fa#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n### 8. Chat Sentiment Analysis (Sentiment)\n\n**Location:** `src/components/plots/Sentiment.tsx`  \n**Description:**  \nThis 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).\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/f8144a10-b072-437d-a156-f5d4cb0a9b15#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/d5a27931-08fa-43cd-9588-ad55b17f9505#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n### 9. Sentiment Word Insights (SentimentWord)\n\n**Location:** `src/components/plots/SentimentWord.tsx`  \n**Description:**  \nFor 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.\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/fe8d2c26-669e-4771-b425-0d3f6a32e740#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/8ce9cc90-2304-48a9-88cf-2739ec89fa56#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n### 10. Message Density Heatmap (HeatmapMonthWeekday)\n\n**Location:** `src/components/plots/HeatmapMonthWeekday.tsx`  \n**Description:**  \nThis 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.\n\n\u003c!-- Dark Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/613c92e7-37b3-4346-8971-2d336593dcc5#gh-dark-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n\u003c!-- Light Mode Image --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/cf574bf7-1523-4276-87cb-1d22c7e726c4#gh-light-mode-only\" width=\"500\"\u003e\n\u003c/p\u003e\n\n## Message Filtering Options\n\nThe 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.\n\n- **Start Date and End Date:**  \n  Specify the time period for the messages to be included in the analysis.\n\n- **Use Abbreviations / Use Full Names:**  \n  Toggle between displaying abbreviated names or full names. This is particularly useful in group chats with many participants, helping to keep the visualizations clear.\n\n- **Select Weekdays:**  \n  Choose which weekdays to include in the analysis, allowing you to observe trends on specific days.\n\n- **Select Senders:**  \n  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.\n\n- **Message Share (%):**  \n  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.\n\nAdditionally, there are two buttons to control these filters:\n\n- **Apply:**  \n  The filters are only applied when you press the \"Apply\" button.\n- **Reset:**  \n  The \"Reset\" button clears the current filter selections. After resetting, you must press \"Apply\" again for the changes to take effect.\n\n## Contributing\n\nThis 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:\n\n1. **Fork the Repository:** Click the \"Fork\" button on GitHub.\n2. **Create a Feature Branch:** Follow the naming convention `feature/\u003cyour-feature-name\u003e`.\n3. **Make Your Changes:** Commit with clear and concise messages.\n4. **Open a Pull Request:** Submit your PR and adhere to the contribution guidelines.\n\nAll changes are automatically tested and built via our CI workflows. Only merged PRs are pushed to master to maintain a stable codebase.\n\n## Acknowledgments\n\nSpecial 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! 🙏\n\n## Workflows\n\n- **Testing:** Automated tests run on every push.\n- **Building:** Build workflows are triggered after each merged PR.\n- **Branch Policy:** Direct pushes to master are restricted; use feature branches and PRs.\n\n## Branch Naming Conventions\n\nTo maintain a clear and structured workflow, we follow a standardized naming convention for branches. Each branch name follows the format:\n\n```\n\u003ctype\u003e/\u003cissue-number\u003e-\u003cshort-description\u003e\n```\n\n### 🚀 Feature Branches\n\n**When to use:** When developing a new feature.  \n**Format:** `feature/\u003cISSUE-NUMBER\u003e-\u003cDESCRIPTION\u003e`  \n**Example:** `feature/50-add-better-welcome-screen`\n\n### 🛠️ Fix Branches\n\n**When to use:** When fixing a bug or an issue.  \n**Format:** `fix/\u003cISSUE-NUMBER\u003e-\u003cDESCRIPTION\u003e`  \n**Example:** `fix/51-update-dependencies`\n\n### 🔄 Refactor Branches\n\n**When to use:** When improving existing code without adding new features.  \n**Format:** `refactor/\u003cISSUE-NUMBER\u003e-\u003cDESCRIPTION\u003e`  \n**Example:** `refactor/60-cleanup-auth-service`\n\n### 📖 Docs Branches\n\n**When to use:** When updating documentation files.  \n**Format:** `docs/\u003cISSUE-NUMBER\u003e-\u003cDESCRIPTION\u003e`  \n**Example:** `docs/72-update-api-readme`\n\n### ✅ Test Branches\n\n**When to use:** When adding or improving tests.  \n**Format:** `test/\u003cISSUE-NUMBER\u003e-\u003cDESCRIPTION\u003e`  \n**Example:** `test/85-add-user-service-tests`\n\nBy following this convention, we ensure better organization, easier tracking, and a smoother development process.\n\n## Repo Activity\n\n![Alt](https://repobeats.axiom.co/api/embed/9a02c54f5c7700208516e9afb7c9609fc568c1c3.svg 'Repobeats analytics image')\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrievoe97%2Fwhatsapp-dashboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrievoe97%2Fwhatsapp-dashboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrievoe97%2Fwhatsapp-dashboard/lists"}