Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:- web/src/analytics/MessageDataProcessor.js
- web/src/analytics/processors/statisticsProcessor.js
- web/src/analytics/processors/timePeriodProcessor.js
- web/src/analytics/processors/heatmapProcessor.js
- web/src/Pages/SearchSQLite/components/ResultsStep.jsx
- web/src/analytics/components/StatisticsDisplay.jsx
- web/src/analytics/components/ActivityChart.jsx
- web/src/analytics/components/MessagesOverTimeChart.jsx
- web/src/analytics/constants.js
- web/src/analytics/utils/dataStructureHelpers.js
Introduction
The Data Analytics and Visualization system is a core feature of the web application, responsible for processing raw message data fetched from the SQLite database and transforming it into meaningful insights and charts. This system is designed with a modular architecture, centered around the MessageDataProcessor class, which acts as a facade to orchestrate various specialized processors for different types of analysis, such as time-based trends, activity patterns, and summary statistics.
The processed data is then consumed by a set of React components that use the amCharts library to render interactive visualizations. This separation of concerns—data processing from data presentation—allows for clear logic and easier maintenance. The entire process is initiated within the ResultsStep component, which is the final stage of the user's journey in the application.
Sources: web/src/analytics/MessageDataProcessor.js, web/src/Pages/SearchSQLite/components/ResultsStep.jsx
System Architecture
The analytics system follows a clear data flow, starting from the UI, passing through the central processor, and ending with the rendering of charts.
The diagram below illustrates the high-level architecture of the analytics module.
Core Components
MessageDataProcessor
This class is the central hub for all data analysis. It is instantiated with the list of messages and a date range. It uses lazy-loading and caching for its processed data; analysis methods are only run once, and the results are stored in private properties (e.g., _messagesPerDay).
Sources: web/src/analytics/MessageDataProcessor.js:8-25
The class diagram below shows its structure and public methods.
Data Processors
The MessageDataProcessor delegates specific analysis tasks to specialized processor classes.
| Processor | Responsibility | Source File |
|---|---|---|
TimePeriodProcessor | Groups messages by day, month, or year within the specified date range. | web/src/analytics/processors/timePeriodProcessor.js |
PatternProcessor | Groups messages by recurring patterns like hour of the day, day of the week, or month of the year. | web/src/analytics/MessageDataProcessor.js:65-92 (Note: File patternProcessor.js is referenced but not provided) |
HeatmapProcessor | Generates a data structure suitable for a heatmap, mapping message counts to weekdays and hours. | web/src/analytics/processors/heatmapProcessor.js |
StatisticsProcessor | Calculates comprehensive summary statistics, including message counts, durations, and activity streaks. | web/src/analytics/processors/statisticsProcessor.js |
StatisticsProcessor
This processor calculates a wide range of metrics. It initializes a data structure for each chat and iterates through all messages to populate it. It also calculates activity streaks by analyzing messages per day.
The general flow of processStatistics is as follows:
The processor tracks the following message types defined in constants.js.
| Message Type |
|---|
text |
link |
image |
audio |
document |
video |
revoked |
sticker |
location |
contact |
poll |
edit |
star |
Sources: web/src/analytics/constants.js:5-19
Visualization Components
The processed data is rendered by a series of React components.
ResultsStep.jsx
This component serves as the entry point for the analytics view. It instantiates MessageDataProcessor and passes the processor instance or its data down to child visualization components.
// web/src/Pages/SearchSQLite/components/ResultsStep.jsx:12-15
function ResultsStep({ isLoading, messagesList, startDateSelected, endDateSelected }) {
// ...
const dataProcessor = new MessageDataProcessor(messagesList, startDateSelected, endDateSelected);
const chatName = dataProcessor.chatNames[0];
const stats = dataProcessor.getMessagesStatistics()[chatName];
// ...
}
Sources: web/src/Pages/SearchSQLite/components/ResultsStep.jsx:12-15
StatisticsDisplay.jsx
This component displays the summary statistics generated by StatisticsProcessor. It features:
- A prominent display of the total message count.
- A series of progress bars showing the percentage distribution of different message types.
- A list of key metrics like first/last message dates, audio durations, and activity streaks.
The component uses pretty-ms to format time durations for readability.
Sources: web/src/analytics/components/StatisticsDisplay.jsx:9-178
The main statistics displayed are:
| Label | Value Source |
|---|---|
| First message sent on: | stats.firstMessageTime |
| Last message sent on: | stats.lastMessageTime |
| Longest audio lasts: | stats.longestAudio |
| Total audio duration: | stats.totalAudioDuration |
| Average audio duration: | stats.avgAudioDuration |
| Longest days streak: | stats.longestDaysStreak |
| Days with at least one message: | stats.dayWithMessages |
Sources: web/src/analytics/components/StatisticsDisplay.jsx:77-101
ActivityChart.jsx & MessagesOverTimeChart.jsx
These are wrapper components that contain a SelectPicker to allow users to switch between different data views.
ActivityCharttoggles between pattern-based data (hourPerDay,dayPerWeek,monthPerYear) and theheatMapHourPerDay.MessagesOverTimeCharttoggles between time-series data (day,month,year).
Based on the user's selection, they fetch the corresponding data from the MessageDataProcessor instance and render the appropriate chart component (ColumnCategoryChart, HeatMapChart, or ColumnDateChart).
Sources: web/src/analytics/components/ActivityChart.jsx:10-43, web/src/analytics/components/MessagesOverTimeChart.jsx:10-34