Developer Setup Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides instructions for setting up the development environment for the WhatsApp Chat Analytics project. The project is composed of two main parts: a Python-based decryption tool (chatsExporter) and a React-based web application (web) for data visualization and analysis. This document covers the prerequisites, dependencies, and steps required to run both components locally.
The overall workflow involves first using the Python tool to decrypt WhatsApp backup files and then using the web application to upload and analyze the resulting database. All processing is done locally on the user's machine to ensure privacy.
Sources: README.md:1-15
Prerequisites
Before starting, ensure the following software is installed on your development machine.
| Software | Required Version | Purpose |
|---|---|---|
| Python | 3.9 or newer | To run the backup decryption script. |
| Node.js | 18 or newer | To run the React web application. |
| adb (optional) | N/A | To transfer backup files from an Android device. |
You will also need the following files from your WhatsApp backup:
- WhatsApp Encryption Key: A 64-character hexadecimal code.
- WhatsApp Backup Files: The
.crypt15files from your Android phone, typically found inAndroid/media/com.whatsapp/WhatsApp/Databases. - Chat List JSON: A
model-storage-chat.jsonfile exported from WhatsApp Web.
Sources: README.md:17-27
Backend Setup (chatsExporter)
The chatsExporter component is a Python script responsible for decrypting the encrypted .crypt15 WhatsApp backup files into a readable SQLite database (.db).
Sources: README.md:13-14, chatsExporter/whatsapp_db_android_exporter.py
1. Install Dependencies
The script depends on wa-crypt-tools, which is installed automatically via pip if not found. The installation is triggered by the ensure_wa_tools_installed function within the script.
# chatsExporter/whatsapp_db_android_exporter.py:30-38
def ensure_wa_tools_installed(force: bool = False) -> None:
"""Ensure wacreatekey/wadecrypt are available (install wa-crypt-tools if needed)."""
if not force and shutil.which("wacreatekey") and shutil.which("wadecrypt"):
return
print("Installing wa-crypt-tools via pip...")
args = [sys.executable, "-m", "pip", "install"]
if force:
args += ["--upgrade", "--force-reinstall"]
args += ["git+https://github.com/ElDavoo/wa-crypt-tools%22%5D
subprocess.run(args, check=True)
2. Configuration
Configuration is managed through a .env file in the chatsExporter/ directory. Copy .env.example to .env and provide the necessary values.
| Variable | Description |
|---|---|
ENCRYPTION_KEY | Your 64-character WhatsApp backup encryption key. |
TARGET_DIR | The directory path containing your .crypt15 backup files. |
Sources: [README.md:50-55](https://github.com/matteomorari/whatsapp-chat-analytics/blob/HEAD/%22git%2Bhttps%3A//github.com/ElDavoo/wa-crypt-tools%22%5D%0A%20%20%20%20subprocess.run(args%2C%20check%3DTrue)%0A%60%60%60%0A%0A### 2. Configuration
Configuration is managed through a .env file in the chatsExporter/ directory. Copy .env.example to .env and provide the necessary values.
| Variable | Description |
|---|---|
ENCRYPTION_KEY | Your 64-character WhatsApp backup encryption key. |
TARGET_DIR | The directory path containing your .crypt15 backup files. |
Sources: [README.md:50-55), chatsExporter/whatsapp_db_android_exporter.py:4-7
3. Running the Decryption Script
Execute the script from within the chatsExporter directory.
cd ".\chatsExporter"
python whatsapp_db_android_exporter.py
This command initiates the decryption process, which produces an unlocked msgstore.db file in the TARGET_DIR.
Sources: README.md:57-59
Decryption Process Flow
The following diagram illustrates the workflow of the whatsapp_db_android_exporter.py script.
This diagram shows the sequence of operations performed by the script, from configuration loading to the final decrypted database generation.
Sources: chatsExporter/whatsapp_db_android_exporter.py:78-142
Frontend Setup (web)
The web component is a React application that provides the user interface for uploading, searching, and analyzing the decrypted chat database. It is bootstrapped with Create React App and customized using react-app-rewired.
Sources: README.md:14-15, web/package.json
1. Install Dependencies
Navigate to the web directory and install the required Node.js packages defined in package.json.
cd ".\web"
npm install
Key dependencies include:
| Package | Version | Description |
|---|---|---|
react | ^18.2.0 | Core library for building the UI. |
@amcharts/amcharts5 | ^5.4.2 | Library for creating interactive charts. |
sql.js | ^1.13.0 | SQLite client for the browser. |
rsuite | ^5.37.4 | A suite of React UI components. |
react-app-rewired | ^2.2.1 | Overrides Create React App webpack configs. |
Sources: web/package.json:4-23, 49-53
2. Webpack Configuration Overrides
The project uses react-app-rewired to customize the webpack configuration without ejecting. The web/config-overrides.js file adds browser-compatible polyfills for Node.js core modules like crypto, vm, and stream, which are necessary for dependencies like sql.js to function correctly in the browser.
// 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, web/package.json:26
3. Running the Development Server
Start the React development server using the start script.
npm start
This will launch the application, which is typically available at http://localhost:3000. The main entry point for the React application is web/src/index.jsx, which renders the App component into the div#root element in web/public/index.html.
Sources: README.md:76-81, web/package.json:26, web/public/index.html:21, web/src/index.jsx:8-12
Full Application Workflow
The complete developer and user workflow involves both the backend and frontend components working in sequence.
This sequence shows the end-to-end process, from decrypting the database to viewing the final analysis in the web application. The React application guides the user through a three-step process: Upload, Search, and Results.
Sources: README.md:29-89, web/src/Pages/SearchSQLite/index.jsx:49-80, web/src/Pages/SearchSQLite/components/UploadStep.jsx:13-50