Project Structure
Relevant source files
The following files were used as context for generating this wiki page:
This project is designed to unlock, analyze, and visualize WhatsApp chat history from Android backups. The architecture is split into two distinct, cooperative parts: a backend Python tool for decryption and a frontend web application for local analysis. All processing occurs on the user's machine, ensuring privacy.
The overall data flow begins with the user providing encrypted backup files (.crypt15) and an encryption key. The backend tool decrypts these into a standard SQLite database (.db). This database, along with a chat list JSON, is then loaded into the frontend application, which runs entirely in the browser to perform searches and render analytical charts.
Sources: README.md
High-Level Architecture
The diagram below illustrates the two main components of the project and the data flow between them.
Backend: chatsExporter
This directory contains the Python-based tool responsible for decrypting the WhatsApp backup files.
Sources: README.md:12-13
Core Component: whatsapp_db_android_exporter.py
This script is the heart of the backend process. It orchestrates the decryption by leveraging the wa-crypt-tools library.
Decryption Workflow
The script follows a clear sequence of steps to produce a readable database file.
- Load Configuration: Reads
ENCRYPTION_KEYandTARGET_DIRfrom a.envfile. - Install Dependencies: Ensures
wa-crypt-toolsis installed via pip. It can force re-installation if needed. - Validate Key: The 64-character hexadecimal encryption key is validated and trimmed of any separators.
- Create Key File: It uses the
wacreatekeycommand-line tool to generate a.keyfile from the hex key. - Find Backups: Scans the target directory for
.crypt15files. - Decrypt Files: For each
.crypt15file found, it runs thewadecryptcommand, using the generated.keyfile to produce a decrypted.dbfile (e.g.,msgstore_YYYY-MM-DD.db).
Sources: chatsExporter/whatsapp_db_android_exporter.py
The following diagram shows the execution flow within whatsapp_db_android_exporter.py.
Configuration
The script is configured via a .env file in the chatsExporter directory.
| Variable | Description | Required |
|---|---|---|
ENCRYPTION_KEY | The 64-character WhatsApp backup encryption key. | Yes |
TARGET_DIR | The directory path containing the .crypt15 backup files. | No |
Sources: chatsExporter/whatsapp_db_android_exporter.py:4-8, chatsExporter/whatsapp_db_android_exporter.py:93-97
Frontend: web
The web/ directory contains a React-based single-page application (SPA) that allows users to upload, search, and analyze their decrypted chat database. All operations are performed client-side.
Sources: README.md:14-15, web/package.json
Key Technologies
The frontend relies on several key libraries to function:
| Library | Purpose |
|---|---|
react | Core UI library for building the user interface. |
rsuite | A suite of React components for UI elements like pickers and grids. |
sql.js | A JavaScript library to run SQLite queries directly in the browser. |
@amcharts/amcharts5 | A powerful library for creating interactive charts and visualizations. |
moment | For robust date and time parsing and manipulation. |
Sources: web/package.json:5-21
Application Flow
The user interface is structured as a three-step wizard, managed by the SearchSQLite component.
This diagram shows the interaction between the user, the React UI, the in-browser SQL engine, and the data processing logic.
Sources: web/src/Pages/SearchSQLite/index.jsx, web/src/Pages/SearchSQLite/components/ResultsStep.jsx
Core Components
SearchSQLite/index.jsx: The main stateful component that manages the current step (UPLOAD,SEARCH,RESULTS) and orchestrates the data flow between steps. It uses custom hooks (useFileUpload,useMessageSearch) to manage state for file handling and search parameters.UploadStep.jsx: Provides UI for uploading themsgstore.dbandmodel-storage-chat.jsonfiles using thersuiteUploader component.SearchStep.jsx: Displays filter controls likeDateRangePicker,CheckPicker(for media type), andSelectPicker(for chat selection).ResultsStep.jsx: Renders the final analysis. It instantiatesMessageDataProcessorwith the fetched messages and passes the processed data to various chart and statistics components.
Sources: web/src/Pages/SearchSQLite/index.jsx, web/src/Pages/SearchSQLite/components/UploadStep.jsx, web/src/Pages/SearchSQLite/components/SearchStep.jsx, web/src/Pages/SearchSQLite/components/ResultsStep.jsx
Analytics Engine
The web/src/analytics directory contains the logic for processing message data and preparing it for visualization.
MessageDataProcessor.js
This is the central class for all analytics operations. It takes the raw message list from the SQL query and provides methods to get structured data for charts and statistics. It acts as a facade, delegating processing to specialized "processor" classes.
The diagram below shows the structure of the MessageDataProcessor and its relationship with its subordinate processors.
Analytics Components
The processed data is rendered by a set of dedicated React components:
StatisticsDisplay.jsx: Shows a summary of key metrics like total messages, message type distribution, and duration statistics for audio.ActivityChart.jsx: A component that allows switching between different views of user activity, such as messages by hour of the day, day of the week, or a full heatmap. It renders either aColumnCategoryChartor aHeatMapChart.MessagesOverTimeChart.jsx: Visualizes message volume over time, allowing the user to group data by day, month, or year.
These components are exported together from analytics/index.js for easy consumption by the rest of the application.
Sources: web/src/analytics/index.js, web/src/analytics/components/StatisticsDisplay.jsx, web/src/analytics/components/ActivityChart.jsx, web/src/analytics/components/MessagesOverTimeChart.jsx
Summary
The whatsapp-chat-analytics project employs a robust two-part structure. The chatsExporter backend handles the complex, system-dependent task of decryption using Python and external command-line tools. The web frontend leverages modern web technologies like React and sql.js to create a powerful, private, and entirely client-side analysis tool. This clear separation of concerns makes the project maintainable and effective, with each part specialized for its role.
Sources: README.md, chatsExporter/whatsapp_db_android_exporter.py, web/src/App.jsx