The `web` Component Architecture
Relevant source files
The following files were used as context for generating this wiki page:- web/src/App.jsx
- web/src/Pages/SearchSQLite/index.jsx
- web/src/analytics/index.js
- web/src/analytics/MessageDataProcessor.js
- web/src/Pages/SearchSQLite/components/UploadStep.jsx
- web/src/Pages/SearchSQLite/components/SearchStep.jsx
- web/src/Pages/SearchSQLite/components/ResultsStep.jsx
- web/src/analytics/components/StatisticsDisplay.jsx
- web/src/analytics/components/ActivityChart.jsx
- web/package.json
- web/public/index.html
- web/src/index.jsx
- web/config-overrides.js
- web/src/analytics/processors/heatmapProcessor.js
- web/src/analytics/processors/statisticsProcessor.js
The web directory contains a React-based single-page application (SPA) designed for local analysis of WhatsApp chat exports. The architecture is centered around a user-friendly, multi-step wizard that guides the user through uploading chat data, applying filters, and viewing generated analytics and visualizations. All processing is performed client-side, ensuring user data remains private.
The application leverages a component-based structure, separating concerns between UI, state management, data processing, and visualization. It uses react-router-dom for routing, rsuite for UI components, and @amcharts/amcharts5 for rendering interactive charts. Webpack fallbacks and providers are configured to ensure compatibility of Node.js modules like crypto and stream in the browser environment.
Sources: README.md, web/src/App.jsx, web/package.json, web/config-overrides.js
Core Technologies and Dependencies
The application is built on the Create React App toolchain, extended with react-app-rewired for custom Webpack configurations. The key dependencies define the application's capabilities.
| Dependency | Version | Description |
|---|---|---|
react | ^18.2.0 | Core library for building the user interface. |
react-router-dom | ^6.15.0 | Handles client-side routing. |
rsuite | ^5.37.4 | Provides a suite of UI components like pickers, steps, and uploaders. |
@amcharts/amcharts5 | ^5.4.2 | A powerful library for creating data visualizations and charts. |
sql.js | ^1.13.0 | A library to run SQLite on the web, used for querying the msgstore.db file. |
fflate | ^0.8.2 | Used for high-performance compression/decompression, likely for handling file data. |
moment | ^2.29.4 | A library for parsing, validating, manipulating, and formatting dates. |
Sources: web/package.json:4-23
Application Entry & Component Hierarchy
The application is a standard React SPA. The browser loads index.html, which contains the root DOM element <div id="root"></div>. The JavaScript entry point, index.jsx, then renders the main App component into this root element.
The App component sets up the application's routing using react-router-dom. Currently, it defines a single route for the root path (/) that renders the SearchSQLite page, which is the core of the application's functionality.
Sources: web/public/index.html:22, web/src/index.jsx:8-12, web/src/App.jsx:9-16
The following diagram illustrates the high-level component hierarchy.
This diagram shows how the App component renders the SearchSQLite page, which in turn manages the display of different step components and result visualizations.
Sources: web/src/App.jsx:12, web/src/Pages/SearchSQLite/index.jsx:13-23, 102-147, web/src/Pages/SearchSQLite/components/ResultsStep.jsx:9-36
Search & Analysis Wizard
The primary user interface is a three-step wizard managed by the SearchSQLite component. This component uses React state to track the current step (UPLOAD, SEARCH, or RESULTS) and renders the appropriate child component.
Sources: web/src/Pages/SearchSQLite/index.jsx:14, 104-131
The user flow through the wizard is linear, with validation at each stage.
This flow diagram shows the user's progression through the application's main feature.
Sources: web/src/Pages/SearchSQLite/index.jsx:62-92
Step 1: Upload Files
The UploadStep component is responsible for collecting the necessary input files from the user. It uses the Uploader component from the rsuite library to provide a drag-and-drop interface for two files:
msgstore.db: The SQLite database containing chat messages.model-storage-chat.json: A JSON file containing the list of chats.
The parent SearchSQLite component uses the useFileUpload custom hook to manage the state of these files. Once both files are provided, the user can proceed to the next step.
Sources: web/src/Pages/SearchSQLite/components/UploadStep.jsx, web/src/Pages/SearchSQLite/index.jsx:16-30, 65-68, 150
Step 2: Search and Filter
The SearchStep component presents a form with several filters to refine the data for analysis. These filters are implemented using rsuite components:
| Filter | Component | Data Source | Description |
|---|---|---|---|
| Date Range | DateRangePicker | useMessageSearch hook | Allows selecting a start and end date for messages. |
| Message Type | CheckPicker | MEDIA_TYPE_DATA constant | Filters by media type (e.g., image, audio, video). |
| Message Direction | SelectPicker | MESSAGE_DIRECTION_DATA constant | Filters by sent or received messages. |
| Chat | SelectPicker | chatList prop | Allows selecting a specific chat to analyze. |
The state for these filters is managed by the useMessageSearch hook in the SearchSQLite parent component.
Sources: web/src/Pages/SearchSQLite/components/SearchStep.jsx, web/src/Pages/SearchSQLite/index.jsx:33-53
Step 3: View Results
The ResultsStep component is the final stage, where the analytics are displayed. When this step is rendered, it instantiates the MessageDataProcessor with the filtered message list. It then passes this processor instance and its generated data to various visualization components:
ActivityChart: Displays activity patterns like messages per hour/day.MessagesOverTimeChart: Shows message volume over the selected date range.StatisticsDisplay: Presents a table of key statistics.
Sources: web/src/Pages/SearchSQLite/components/ResultsStep.jsx:13-36
Data Processing Engine
The core of the analytics functionality resides within the analytics directory, primarily driven by the MessageDataProcessor class.
Sources: web/src/analytics/MessageDataProcessor.js
MessageDataProcessor Class
This class is the main entry point for processing message data. It takes an array of messages, a start date, and an end date in its constructor. It then uses several specialized processor classes to compute different types of analytics. The results are cached to avoid redundant calculations.
This class diagram shows the structure of MessageDataProcessor and its relationship with the specialized processors it delegates tasks to.
Sources: web/src/analytics/MessageDataProcessor.js, web/src/analytics/processors/heatmapProcessor.js, web/src/analytics/processors/statisticsProcessor.js
Data Processing Flow
When the ResultsStep component is rendered, it triggers a sequence of data processing and rendering operations.
This sequence diagram illustrates how the ResultsStep component uses MessageDataProcessor to get calculated statistics, which are then passed to the StatisticsDisplay component for rendering.
Sources: web/src/Pages/SearchSQLite/components/ResultsStep.jsx:13-16, 33-35, web/src/analytics/MessageDataProcessor.js:126-133, web/src/analytics/processors/statisticsProcessor.js:14-26
Visualization Components
The application uses a set of reusable React components to display the processed data. These components are wrappers around the @amcharts/amcharts5 library.
ActivityChart
The ActivityChart component is a versatile container that can display several types of activity patterns. It uses a SelectPicker to allow the user to switch between different views. Based on the user's selection, it fetches the appropriate data from the dataProcessor and renders either a ColumnCategoryChart or a HeatMapChart.
Sources: web/src/analytics/components/ActivityChart.jsx:13-43
StatisticsDisplay
This component renders a comprehensive summary of message statistics. It receives a stats object and displays the data in a structured format, including a breakdown of message types with progress bars and a list of key metrics like first/last message dates, audio durations, and message streaks.
Sources: web/src/analytics/components/StatisticsDisplay.jsx
Summary
The web component of the whatsapp-chat-analytics project is a well-structured React SPA. It employs a modular architecture with a clear separation of concerns:
- UI and State: Managed by React components, custom hooks, and the
rsuitelibrary. - Data Processing: Encapsulated within the
MessageDataProcessorand its helper classes, providing a clean API for the UI to consume. - Visualization: Handled by dedicated chart components that wrap the
amchartslibrary.
This architecture makes the application maintainable and extensible, allowing for new analytics or visualization types to be added by creating new processor or component modules. The entire process runs locally in the browser, prioritizing user privacy.
Sources: README.md:10, 39, web/src/App.jsx, web/src/analytics/MessageDataProcessor.js