Step 5: Running the Web Application

Relevant source files

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

• web/package.json
• web/src/index.jsx
• README.md
• web/public/index.html
• 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
• web/src/analytics/MessageDataProcessor.js
• web/src/analytics/processors/statisticsProcessor.js
• chatsExporter/whatsapp_db_android_exporter.py

The web application is a client-side tool built with React that allows users to search, filter, and analyze their WhatsApp chat history. All processing happens locally in the user's browser, ensuring that private messages are never uploaded to any server. The application provides a guided, three-step process for uploading data, defining search criteria, and viewing results through interactive charts and statistics.

This application is the user-facing analysis component of the project, complementing the chatsExporter tool which handles the initial decryption of WhatsApp backup files. The entire workflow is designed to be self-contained on the user's machine for maximum privacy and security.

Sources: README.md:10-14, 80-83, web/public/index.html:8-11

Prerequisites and Setup

Before running the web application, certain prerequisites must be met.

• Node.js: Version 18 or newer is required to run the application and manage its dependencies.
• Dependencies Installation: All required npm packages must be installed by navigating to the web/ directory and running the npm install command.

Sources: README.md:21-22, 86-87

Key Dependencies

The web application relies on several key libraries to provide its functionality. The main dependencies are listed in web/package.json.

Library	Version	Description
react	^18.2.0	The core library for building the user interface.
rsuite	^5.37.4	A UI component library used for elements like uploaders, pickers, and navigation steps.
sql.js	^1.13.0	A library to run SQLite queries directly in the browser, used to read the msgstore.db file.
@amcharts/amcharts5	^5.4.2	A data visualization library used to create the interactive charts in the results step.
moment	^2.29.4	A library for parsing, validating, manipulating, and formatting dates.
react-app-rewired	^2.2.1	Used to override the default Create React App webpack configuration without ejecting.

Sources: web/package.json:4-21, 49-51

Starting the Application

The application is started by running the npm start script from within the web/ directory. This command utilizes react-app-rewired to launch a local development server. By default, the application becomes accessible at http://localhost:3000.

Sources: README.md:86-91, web/package.json:24

Application Entry Point

The web application is a standard Single Page Application (SPA) bootstrapped by Create React App.

1. The browser loads web/public/index.html.
2. This HTML file contains a single div element with the ID root.
3. The JavaScript entry point, web/src/index.jsx, finds the root element and uses ReactDOM to render the main <App /> component into it, thereby launching the application.

This diagram illustrates the initial loading sequence of the application.

Application Architecture and User Flow

The core of the web application is the SearchSQLite component, which manages a three-step user workflow. It maintains the current step's state and orchestrates the transitions between them.

This diagram shows the main components involved in the user flow.

Step 1: Upload Files

The initial step requires the user to upload two files generated from the previous steps of the overall process: msgstore.db and model-storage-chat.json.

• Component: UploadStep.jsx
• Functionality: Uses the <Uploader> component from the rsuite library to provide a drag-and-drop interface for file selection.
• Files:
  • msgstore.db: The decrypted SQLite database containing chat messages, obtained from Step 1: Unlock Your Encrypted Backups.
  • model-storage-chat.json: A JSON file containing the list of chats, obtained from Step 2: Get Your Chat List.

The handleNext function in SearchSQLite validates that both files have been uploaded before allowing the user to proceed to the next step.

Sources: web/src/Pages/SearchSQLite/components/UploadStep.jsx:15-70, web/src/Pages/SearchSQLite/index.jsx:52-56, README.md:95-97

Step 2: Search & Filter

Once the files are uploaded, the user can define search criteria to filter the messages.

• Component: SearchStep.jsx
• Functionality: Provides several filter controls:
  • Date Range: A DateRangePicker to select a start and end date. The available range is determined by the earliest and latest message timestamps in the uploaded database.
  • Message Type: A CheckPicker to filter by media type (e.g., image, video, audio).
  • Message Direction: A SelectPicker to choose between incoming, outgoing, or all messages.
  • Chat: A SelectPicker to narrow the analysis to a specific individual or group chat.

The state for these filters is managed within the SearchSQLite parent component via the useMessageSearch hook.

Sources: web/src/Pages/SearchSQLite/components/SearchStep.jsx:26-95, web/src/Pages/SearchSQLite/index.jsx:36-49

Step 3: View Results

After executing the search, the application displays the analysis results.

• Component: ResultsStep.jsx
• Functionality:
  1. Instantiates a MessageDataProcessor with the filtered list of messages.
  2. Uses the processor to calculate statistics and format data for visualization.
  3. Renders several analytics components:
     • ActivityChart: Displays message patterns, such as messages per hour or a daily activity heatmap.
     • MessagesOverTimeChart: Shows message volume over the selected time period.
     • StatisticsDisplay: Presents a summary of key metrics like total messages, message types, and audio duration stats.

The following sequence diagram illustrates the complete user flow from uploading files to viewing results.

Client-Side Data Processing

All data analysis is performed in the browser using JavaScript. The MessageDataProcessor class is the central orchestrator for this task.

• File: web/src/analytics/MessageDataProcessor.js

This class takes the raw message list from the search results and uses a suite of specialized sub-processors to generate different analytical views. It caches the results of these computations to avoid redundant processing.

The diagram below shows the architecture of the MessageDataProcessor and its relationship with other processors.

Summary

The web application provides a powerful, private, and user-friendly interface for WhatsApp chat analysis. By leveraging browser technologies like React for the UI, sql.js for database interaction, and amcharts for visualization, it delivers a rich analytics experience without compromising user data security. The guided three-step process simplifies the workflow, making it accessible for users to upload their decrypted data, filter it according to their needs, and gain insights from the visualized results.

Sources: README.md:10-14, 80-83