Feature: File Upload
Relevant source files
The following files were used as context for generating this wiki page:The File Upload feature is the initial and mandatory step (STEPS.UPLOAD) in the "Search WhatsApp SQLite" page. Its primary purpose is to allow users to upload two specific files from their local machine: the WhatsApp messages database (msgstore.db) and a chat list JSON file (model-storage-chat.json). The entire process is handled client-side to ensure user privacy, with file reading and initial processing occurring directly in the browser.
This feature is orchestrated by the main SearchSQLite component, which uses a dedicated UI component (UploadStep) for rendering the upload boxes and a custom React hook (useFileUpload) to manage the state and logic for each file. A FileService provides utility functions for validation and reading file contents. Successful upload of both files is a prerequisite for proceeding to the subsequent search and analysis steps.
Sources: web/src/Pages/SearchSQLite/index.jsx:13, 56-65, README.md:92-95, web/src/Pages/SearchSQLite/constants.js:25-29
Architecture and Components
The file upload functionality is composed of several distinct parts that work together: a parent orchestrator component, a reusable state management hook, a dedicated UI component, and a service class for file operations.
Sources: web/src/Pages/SearchSQLite/index.jsx, web/src/Pages/SearchSQLite/hooks/useFileUpload.js, web/src/Pages/SearchSQLite/components/UploadStep.jsx, web/src/Pages/SearchSQLite/services/fileService.js
Component Interaction
The following diagram illustrates the relationship between the main components involved in the file upload process.
This diagram shows that the SearchSQLite page instantiates two useFileUpload hooks, one for each file type. It then passes the state and handlers from these hooks as props to the UploadStep UI component. The hooks, in turn, utilize the FileService and DatabaseService to process the uploaded files.
Sources: web/src/Pages/SearchSQLite/index.jsx:16-31, web/src/Pages/SearchSQLite/hooks/useFileUpload.js:2, 3
Key Components
| Component/Hook/Service | File | Description |
|---|---|---|
SearchSQLite | web/src/Pages/SearchSQLite/index.jsx | The main page component. It manages the overall step-based workflow and orchestrates the file upload process by using two instances of useFileUpload. |
useFileUpload | web/src/Pages/SearchSQLite/hooks/useFileUpload.js | A custom React hook responsible for managing the state and processing logic for a single file upload. It is initialized with a type ('messages' or 'chats'). |
UploadStep | web/src/Pages/SearchSQLite/components/UploadStep.jsx | A React component that renders the two drag-and-drop upload areas for the .db and .json files using the rsuite Uploader component. |
FileService | web/src/Pages/SearchSQLite/services/fileService.js | A class with static methods for file validation (by extension), reading file contents as an ArrayBuffer or text, and parsing the chat JSON file. |
Sources: web/src/Pages/SearchSQLite/index.jsx:13, web/src/Pages/SearchSQLite/hooks/useFileUpload.js:8, web/src/Pages/SearchSQLite/components/UploadStep.jsx:8, web/src/Pages/SearchSQLite/services/fileService.js:4
Data Flow and Processing
When a user drops a file into one of the upload zones, a sequence of events is triggered to validate, read, and process the file content, all within the browser.
File Upload Sequence
The sequence diagram below details the interactions that occur when a user uploads a file.
This flow shows the user interaction initiating a call to the handler provided by the useFileUpload hook. The hook then uses FileService to validate and read the file, and DatabaseService (for .db files) or FileService (for .json files) to parse the content before updating its internal state.
Sources: web/src/Pages/SearchSQLite/components/UploadStep.jsx:26, web/src/Pages/SearchSQLite/hooks/useFileUpload.js:34-43
useFileUpload Hook Logic
The useFileUpload hook is central to the feature. It takes a type string ('messages' or 'chats') to determine its behavior.
This flowchart visualizes the logic within the handleFileUpload function. It first validates the file, then branches based on the type to either process a database file or a JSON chat list, and finally updates the component's state. If any step fails, an error is shown, and the state is cleared.
Sources: web/src/Pages/SearchSQLite/hooks/useFileUpload.js:32-51
File Requirements and Processing
The system requires two specific files, each processed differently.
| File Name | Expected Extension | Validation | Processing Method | Output |
|---|---|---|---|---|
msgstore.db | .db | FileService.validateFile(file, 'messages') | FileService.readAsArrayBuffer followed by DatabaseService.initializeFromFile | An initialized DatabaseService instance. |
model-storage-chat.json | .json | FileService.validateFile(file, 'chats') | FileService.readAsText followed by FileService.parseChatFile | An array of chat objects (chatList). |
The parseChatFile method transforms the raw JSON data into a structured array, where each object contains an id, name, and type.
Sources: web/src/Pages/SearchSQLite/services/fileService.js:8-15, 41-52, web/src/Pages/SearchSQLite/hooks/useFileUpload.js:21-28
UI Implementation
The user interface for the upload step is defined in the UploadStep.jsx component. It presents two distinct, styled drop-zones.
- Component Library: It uses the
<Uploader>component from thersuitelibrary. - Configuration: The uploader is configured to be
draggable, accept only a single file (multiple={false}), and prevent automatic uploads (autoUpload={false}). - State: The component is stateless and receives file information and event handlers (
on...FileChange,onClear...) as props from its parent,SearchSQLite. - User Feedback: When a file is selected, its name is displayed within the upload box. The upload box is disabled (
disabled={file !== null}) to prevent uploading a new file until the current one is cleared.
Sources: web/src/Pages/SearchSQLite/components/UploadStep.jsx:15-68, web/src/Pages/SearchSQLite/searchSQLite.css:27-61
Conclusion
The File Upload feature is a robust, client-side mechanism that serves as the entry point for the chat analysis tool. It effectively uses a combination of React components, custom hooks, and service classes to create a clear separation of concerns between UI, state management, and business logic. By handling all file operations in the browser, it upholds the project's commitment to user privacy. The successful upload and processing of both the msgstore.db and model-storage-chat.json files are critical for enabling all subsequent data search and visualization functionalities.
Sources: README.md:4, web/src/Pages/SearchSQLite/index.jsx:58-62