Project Philosophy & Privacy
Relevant source files
The following files were used as context for generating this wiki page:
The fundamental philosophy of WhatsApp Chat Analytics is to provide powerful chat analysis tools while ensuring user privacy through an entirely local processing model. All operations, from decryption to data visualization, are executed on the user's own machine. User messages and metadata are never uploaded to any external server, guaranteeing that the data remains confidential and under the user's control.
This commitment is evident in the project's architecture, which is split into two distinct, local-first components: a Python-based decryption tool (chatsExporter) and a browser-based analysis application (web). The system is designed so that sensitive data, such as the WhatsApp encryption key and the chat database itself, never leaves the user's local environment.
Sources: README.md:3-4, README.md:82-83
Core Principle: Local-First Processing
The entire workflow is designed to run offline on the user's computer. The project explicitly states that "Everything runs on your own computer — your messages stay private and never leave your device." This is not just a feature but the core design principle. The analysis happens within the web browser, and messages are not sent to any server.
Sources: README.md:3-4, README.md:82-83
Data Flow and Privacy
The data flow is structured to prevent any leakage of private information to the internet. The user manually transfers encrypted files from their phone to their PC, decrypts them locally, and then loads the resulting database into a web application that runs entirely in their browser.
The following diagram illustrates the privacy-centric data flow:
This diagram shows that all user data (green) and processing steps (yellow) remain within the user's local environment.
Sources: README.md:29-80
System Components and Privacy Boundaries
The project is divided into two main components, each with a specific role that reinforces the local-only privacy model.
| Component | Directory | Description | Privacy Role |
|---|---|---|---|
| Chat Exporter | chatsExporter/ | A Python tool to decrypt .crypt15 backup files. | Decrypts sensitive data locally using a user-provided key. No network activity is performed. |
| Web Application | web/ | A React-based single-page application for searching and visualizing chat data. | Loads the decrypted database directly into the browser. All parsing, querying, and analysis are done client-side. |
Sources: README.md:12-15, chatsExporter/whatsapp_db_android_exporter.py, web/src/Pages/SearchSQLite/index.jsx
chatsExporter: Local Decryption
The decryption process is handled by the whatsapp_db_android_exporter.py script. This script requires the user's 64-character ENCRYPTION_KEY and the path to the backup files (TARGET_DIR), which are configured in a local .env file. The script then uses the wa-crypt-tools library to perform the decryption entirely on the user's machine.
The key steps are:
- Load
ENCRYPTION_KEYfrom the local.envfile. - Validate the 64-character hexadecimal key.
- Run the
wacreatekeyandwadecryptcommand-line tools as local subprocesses. - The output is a decrypted
.dbfile saved in the same local directory.
At no point is the encryption key or the database content transmitted over the network.
Sources: chatsExporter/whatsapp_db_android_exporter.py:4-8, chatsExporter/whatsapp_db_android_exporter.py:73-76, chatsExporter/whatsapp_db_android_exporter.py:59-62
web: In-Browser Analysis
The web/ directory contains a React application that performs all analysis within the user's browser. This is made possible by leveraging JavaScript libraries that can handle file processing and database operations on the client side.
The privacy-preserving sequence is as follows:
This sequence demonstrates that once the files are loaded, all subsequent operations—querying the database, processing data, and rendering visualizations—occur exclusively within the browser sandbox. The use of sql.js, as listed in the dependencies, is critical to this architecture, as it provides an in-browser SQL database engine.
Sources: web/package.json:18, web/src/Pages/SearchSQLite/index.jsx:11-30, web/src/Pages/SearchSQLite/components/UploadStep.jsx:11-27, web/src/analytics/MessageDataProcessor.js:10-14
User Responsibility and Disclaimer
While the tool is built with privacy as a priority, the project's README.md includes an important disclaimer that places the responsibility of ethical use on the user.
Key points from the disclaimer include:
- The tool is intended for personal use only.
- Users should only analyze their own WhatsApp backups.
- Users must respect privacy laws and WhatsApp's terms of service.
- The software is provided "as is" without any warranties, and the user is solely responsible for how they use it.
This emphasizes that the project provides a technical capability, but the ethical and legal obligations remain with the user.
Sources: README.md:85-96