# pustur/whatsapp-chat-parser-website architecture

> Architecture diagram of the GitHub repository pustur/whatsapp-chat-parser-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pustur/whatsapp-chat-parser-website
- Repository: https://github.com/pustur/whatsapp-chat-parser-website

## Overview

This project is a client-side web application built with React and TypeScript that allows users to upload and parse WhatsApp chat logs (in TXT or ZIP formats). The primary goal is to process an uploaded chat, extract text and media content (when available), and then display the chat in a user-friendly manner. The project uses several libraries (such as JSZip for handling ZIP files, the npm package “whatsapp-chat-parser” for parsing, and Styled Components for CSS styling) and a simple state management solution (using Jotai via custom store files).

##### Main Components
- UI/Frontend Layer:
- index.html & public/manifest.json: The static hosting and initial HTML file.
- React Components (located under src/components) including:
▪ Dropzone: For file upload.
▪ MessageViewer & Message: To display parsed chat messages.
▪ Filter components and ActiveUserSelector: To interact with filtered data.
▪ Credits, Poll, and Sidebar: Additional UI/UX elements.
- State Management:
- Stores (src/stores/global.ts and src/stores/filters.ts): Manage global and filter-specific states using Jotai.
- Utility & Parsing Layer:
- Integration with external libraries: whatsapp-chat-parser and JSZip.
- Build & Configuration:
- Vite configuration (vite.config.ts, tsconfig.json) and build scripts (npm start, npm run build).
- Linting and Prettier configuration files (.eslintrc, .prettierrc, etc.).
- Assets:
- Static assets (images, example chat ZIP in src/assets) that support UI display and testing.

##### Relationships and Interactions
- The user initiates the process by uploading a file using the Dropzone component.
- The file is then processed: if it is a ZIP file, JSZip is invoked to extract the contents.
- The extracted chat content is fed into the “whatsapp-chat-parser” library to convert it into a structured format.
- Parsed data is stored in state (using Jotai-managed stores) and then passed to various display components (MessageViewer, Message, etc.).
- Supporting components (e.g., FilterMessageDatesForm, FilterMessageLimitsForm, FilterModeSelector) interact with the state to provide filtering and user customization features.
- The UI updates dynamically based on state changes, giving the user immediate feedback.

##### Important Architectural Patterns and Design Principles
- Component-based architecture: The project is modular, with clearly separated components for upload, parsing, state management, and UI rendering.
- Unidirectional data flow: User actions (upload, filter changes) update global state, which then propagates to presentation components.
- Separation of concerns: Parsing logic is separated from the UI code; utilities and styling are modular.
- Reusability: Many React components (e.g., for displaying messages, polls, or filtering options) are designed to be reused across the application.

##### Final Recommendations
- Make it clear through labels and annotations why each component exists and how they interact, ensuring that any observer (especially someone familiar with system design) quickly understands the overall architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global External Actor
    User["User"]:::external

    %% UI/Frontend Layer
    subgraph "UI/Frontend Layer"
        HTML["index.html"]:::frontend
        Manifest["Manifest file"]:::frontend
        Dropzone["File Upload (Dropzone)"]:::frontend
        MessageViewer["MessageViewer (Chat Display)"]:::frontend
        Message["Message (Individual Chat Message)"]:::frontend
        FilterDates["FilterMessageDatesForm"]:::frontend
        FilterLimits["FilterMessageLimitsForm"]:::frontend
        FilterMode["FilterModeSelector"]:::frontend
        ActiveUser["ActiveUserSelector"]:::frontend
        Credits["Credits (UI Element)"]:::frontend
        Poll["Poll (UI Element)"]:::frontend
        Sidebar["Sidebar (Navigation)"]:::frontend
    end

    %% State Management Layer
    subgraph "State Management"
        GlobalStore["Global Store (Jotai)"]:::state
        FiltersStore["Filters Store (Jotai)"]:::state
    end

    %% Utility & Parsing Layer
    subgraph "Utility & Parsing Layer"
        ChatParser["Chat Parser (JSZip + whatsapp-chat-parser)"]:::utility
        Colors["Colors Utility"]:::utility
        PollParser["Poll Parser Utility"]:::utility
        StylesUtil["Styles Utility"]:::utility
        UniqueID["Unique ID Generator"]:::utility
        ZIndex["Z-index Management Utility"]:::utility
        OtherUtils["Other Utilities"]:::utility
    end

    %% Assets Layer
    subgraph "Assets"
        StaticAssets["Static Assets"]:::asset
        WhatsAppExample["WhatsApp Chat Example"]:::asset
    end

    %% Build & Configuration Layer
    subgraph "Build & Configuration"
        ViteConfig["Vite Config"]:::config
        TSConfig["TypeScript Config"]:::config
        ESLint["ESLint Config"]:::config
        Prettier["Prettier Config"]:::config
    end

    %% Relationships
    User -->|"uploads"| Dropzone
    Dropzone -->|"extracts file"| ChatParser
    ChatParser -->|"parses chat"| GlobalStore
    ChatParser -->|"uses"| Colors
    ChatParser -->|"uses"| PollParser
    ChatParser -->|"uses"| StylesUtil
    ChatParser -->|"uses"| UniqueID
    ChatParser -->|"uses"| ZIndex
    ChatParser -->|"uses"| OtherUtils

    GlobalStore -->|"renders state to"| MessageViewer
    GlobalStore -->|"renders state to"| Message
    GlobalStore -->|"renders state to"| Sidebar
    GlobalStore -->|"renders state to"| ActiveUser

    FilterDates -->|"updates"| GlobalStore
    FilterLimits -->|"updates"| GlobalStore
    FilterMode -->|"updates"| GlobalStore
    GlobalStore -->|"communicates state to"| FiltersStore

    %% Additional UI Elements receiving state
    GlobalStore -->|"renders state to"| Credits
    GlobalStore -->|"renders state to"| Poll

    %% Assets used in UI rendering
    StaticAssets ---|"provides images and files"| MessageViewer
    WhatsAppExample ---|"sample data"| ChatParser

    %% Build & Configuration supports the project
    ViteConfig ---|"builds application"| HTML
    TSConfig ---|"type checks"| GlobalStore
    ESLint ---|"linting quality"| GlobalStore
    Prettier ---|"formatting"| GlobalStore

    %% Connections from static hosting to UI components
    HTML --- Manifest

    %% Click Events for UI/Frontend Layer
    click HTML "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//index.html"
    click Manifest "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//public/manifest.json"
    click Dropzone "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/Dropzone/Dropzone.tsx"
    click MessageViewer "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/MessageViewer/MessageViewer.tsx"
    click Message "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/Message/Message.tsx"
    click FilterDates "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/FilterMessageDatesForm/FilterMessageDatesForm.tsx"
    click FilterLimits "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/FilterMessageLimitsForm/FilterMessageLimitsForm.tsx"
    click FilterMode "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/FilterModeSelector/FilterModeSelector.tsx"
    click ActiveUser "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/ActiveUserSelector/ActiveUserSelector.tsx"
    click Credits "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/Credits/Credits.tsx"
    click Poll "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/Poll/Poll.tsx"
    click Sidebar "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/components/Sidebar/Sidebar.tsx"

    %% Click Events for State Management
    click GlobalStore "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/stores/global.ts"
    click FiltersStore "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/stores/filters.ts"

    %% Click Events for Utility & Parsing Layer
    click Colors "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/utils/colors.ts"
    click PollParser "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/utils/poll-parser.ts"
    click StylesUtil "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/utils/styles.ts"
    click UniqueID "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/utils/unique-id-generator.ts"
    click ZIndex "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/utils/z-index.ts"
    click OtherUtils "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/utils/utils.ts"

    %% Click Events for Assets
    click StaticAssets "https://github.com/pustur/whatsapp-chat-parser-website/tree/master//src/assets/"
    click WhatsAppExample "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//src/assets/whatsapp-chat-parser-example.zip"

    %% Click Events for Build & Configuration
    click ViteConfig "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//vite.config.ts"
    click TSConfig "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//tsconfig.json"
    click ESLint "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//.eslintrc"
    click Prettier "https://github.com/pustur/whatsapp-chat-parser-website/blob/master//.prettierrc"

    %% Class Definitions for Coloring
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef state fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef utility fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef asset fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
