Overall Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• chatsExporter/whatsapp_db_android_exporter.py
• web/package.json
• web/config-overrides.js
• web/src/Pages/SearchSQLite/index.jsx
• web/src/Pages/SearchSQLite/utils/queryBuilder.js
• web/src/analytics/MessageDataProcessor.js
• web/src/analytics/processors/statisticsProcessor.js
• web/src/analytics/components/StatisticsDisplay.jsx
• web/src/analytics/components/charts/heatMapChart.jsx

The WhatsApp Chat Analytics tool is a client-side application designed to decrypt, analyze, and visualize WhatsApp chat history from Android backups. The architecture is split into two distinct, decoupled components: a Python-based decryption tool and a browser-based React web application for analysis. This design prioritizes user privacy by ensuring that all sensitive data, including messages and encryption keys, remains on the user's local machine and is never uploaded to any server.

The core principle is a two-stage process. First, the user runs the Python script to convert encrypted WhatsApp backup files (.crypt15) into a standard SQLite database (.db). Second, the user interacts with a local web application, uploading the decrypted database and a chat list file. All subsequent querying, data processing, and visualization happen entirely within the web browser, leveraging JavaScript libraries to handle database operations and render charts.

Sources: README.md:3-8, 12-15, 78-81

Component Overview

The project is composed of two main parts: chatsExporter and web. They do not communicate directly but rather through files generated by the user.

This diagram illustrates the two-part structure of the application, showing how the user first uses the chatsExporter to produce a .db file and then uses the web application to analyze it along with a chat list JSON.

Sources: README.md:12-15, 33-76

Backend: chatsExporter

The chatsExporter is a command-line utility written in Python responsible for decrypting the WhatsApp backup database.

Sources: README.md:13, chatsExporter/whatsapp_db_android_exporter.py

Decryption Flow

The script orchestrates external command-line tools from wa-crypt-tools to perform the decryption.

1. Setup: The script loads configuration from a .env file.
2. Tool Check: It ensures wacreatekey and wadecrypt from wa-crypt-tools are installed via pip.
3. Key Generation: It uses wacreatekey to convert the user's 64-character hexadecimal key into a binary key file.
4. Decryption: It finds all .crypt15 files in the target directory and runs wadecrypt on each, using the generated key file to produce a decrypted .db file (e.g., msgstore.db).

This flowchart shows the step-by-step process executed by the whatsapp_db_android_exporter.py script.

Sources: chatsExporter/whatsapp_db_android_exporter.py:32-132

Configuration

The script is configured via an .env file in the chatsExporter directory.

Variable	Description	Example
ENCRYPTION_KEY	The 64-character hexadecimal key for the WhatsApp backup.	abcdef123...
TARGET_DIR	The directory path containing the .crypt15 backup files.	./backups

Sources: chatsExporter/whatsapp_db_android_exporter.py:4-6, 43-45

Frontend: web Application

The web component is a single-page application (SPA) built with React. It runs entirely in the user's browser, providing an interface to upload, search, and visualize chat data.

Sources: README.md:14, web/public/index.html:15

Core Technologies

The frontend relies on several key libraries to function without a server backend.

Library	Role	Source
react	The core UI library for building components.	web/package.json:13
sql.js	A library to run a full SQLite database in the browser, compiled to WebAssembly. Used to load and query msgstore.db.	web/package.json:20
@amcharts/amcharts5	A charting library used for creating interactive data visualizations like column charts and heatmaps.	web/package.json:9
rsuite	A UI component library providing elements like date pickers, selectors, and uploaders.	web/package.json:19
react-app-rewired	Used to override the default Webpack configuration to add necessary polyfills for browser compatibility.	web/package.json:24

Webpack Configuration

Because libraries like sql.js depend on Node.js core modules (e.g., crypto, stream), the default Create React App configuration is extended. The config-overrides.js file adds browser-compatible polyfills for these modules, allowing them to run in a browser environment.

// web/config-overrides.js:4-10
module.exports = function override(config) {
  config.resolve.fallback = {
    ...config.resolve.fallback,
    crypto: require.resolve('crypto-browserify'),
    vm: require.resolve('vm-browserify'),
    stream: require.resolve('stream-browserify'),
    path: require.resolve('path-browserify'),
    fs: false, // fs is not typically available in the browser
  };
//...

Sources: web/config-overrides.js:3-10

UI Flow

The main user interface, managed by the SearchSQLite component, is a three-step wizard.

This diagram shows the navigation flow between the three main steps of the analysis UI.

Step	Component	Description
1. Upload	UploadStep.jsx	User uploads the msgstore.db and model-storage-chat.json files.
2. Search	SearchStep.jsx	User defines search criteria like date range, media type, sender, and conversation.
3. Results	ResultsStep.jsx	Displays the resulting analytics, including charts and statistics.

Sources: web/src/Pages/SearchSQLite/index.jsx:4-10, 48-73, 93-146

Data Flow and In-Browser Processing

The most critical aspect of the architecture is how data is handled entirely on the client side.

This diagram details the data flow within the browser, from file upload to the final rendering of analytics.

Sources: web/src/Pages/SearchSQLite/index.jsx, web/src/Pages/SearchSQLite/utils/queryBuilder.js, web/src/analytics/MessageDataProcessor.js

1. Database Querying

When the user proceeds from the "Search" step, the useMessageSearch hook orchestrates the query.

• The buildMessagesQuery function dynamically constructs an SQL SELECT statement based on the filters selected by the user (date range, chat, media type, etc.).
• This SQL query is executed against the in-memory database managed by sql.js.
• The result is an array of message objects.

Sources: web/src/Pages/SearchSQLite/index.jsx:39-45, 68-72, web/src/Pages/SearchSQLite/utils/queryBuilder.js:6-79

2. Data Analysis Engine

The raw message list is fed into the MessageDataProcessor, which acts as a facade for a modular set of analytics processors.

This class diagram shows how MessageDataProcessor delegates specific analysis tasks to specialized processor classes.

• MessageDataProcessor: The main entry point. It receives the raw messages and caches the results of different processing tasks to avoid re-computation.
• TimePeriodProcessor: Groups messages by day, month, or year.
• PatternProcessor: Groups messages by patterns like hour-of-day or day-of-week.
• HeatmapProcessor: Generates a data matrix for heatmap visualizations.
• StatisticsProcessor: Calculates aggregate statistics like total messages, message types, audio duration, and consecutive day streaks.

Sources: web/src/analytics/MessageDataProcessor.js, web/src/analytics/processors/timePeriodProcessor.js, web/src/analytics/processors/heatmapProcessor.js, web/src/analytics/processors/statisticsProcessor.js

3. Visualization

The processed data from MessageDataProcessor is passed as props to various React components in the ResultsStep.

• ActivityChart / MessagesOverTimeChart: These components use amCharts to render interactive column charts and heatmaps.
• StatisticsDisplay: This component renders key metrics and progress bars for message type distribution.

The final output is a dashboard of interactive charts and statistics, rendered locally in the user's browser.

Sources: web/src/Pages/SearchSQLite/components/ResultsStep.jsx:15-37, web/src/analytics/components/StatisticsDisplay.jsx, web/src/analytics/components/charts/heatMapChart.jsx

Conclusion

The architecture of WhatsApp Chat Analytics is a clever combination of a standalone Python script for offline decryption and a powerful, serverless React application for in-browser analysis. By leveraging sql.js to run SQLite in the browser, it achieves a high degree of privacy and security, as user data never leaves the local machine. The frontend's modular design, with a central data processor and distinct visualization components, allows for organized and efficient handling of complex chat analytics.