# voice-less/whatsapp-msgstore-viewer architecture

> Architecture diagram of the GitHub repository voice-less/whatsapp-msgstore-viewer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/voice-less/whatsapp-msgstore-viewer
- Repository: https://github.com/voice-less/whatsapp-msgstore-viewer

## Overview

##### Project Type and Purpose
- A desktop cross-platform (Linux/Windows/Mac) Python application with a Kivy/KivyMD GUI.
- Its core functions are to decrypt (via an embedded Crypt14/Crypt15 decrypter), read, and display WhatsApp SQLite databases (`msgstore.db`, optional `wa.db`) and linked media.

##### High-Level File-Structure Analysis
- MVC layers:
– View/ (all `.kv` files, screen classes under View/*)
– Controller/ (screen controllers chat_screen.py, login_screen.py, etc.)
– Model/ (one model per screen)
- Data access: `dbs/abstract_db.py` plus versioned schemas in `dbs/v1/db.py`.
- Decryption: `decryption/dbs/WhatsAppCrypt14Crypt15Decrypter` subtree wrapping ElDavoo’s CLI library.
- Utilities: `Utility/Utils.py`, `Utility/observer.py` implementing common helpers & observer pattern.
- Assets: fonts, images under assets/.
- Entry point: `main.py`.

A. Frontend (UI)
- Kivy App (main.py) launching a ScreenManager.
- Screens: LoginScreen, MainScreen, ChatScreen, TemplateScreen.
- UI Widgets & Components (custom `.kv` files under View/components/).
B. Controllers
- One controller per screen in Controller/*.py.
- Bridge between View and Model, handles user events.
C. Models & Business Logic
- Screen-specific Model classes in Model/*.py.
- Data aggregation, formatting for UI.
D. Data Layer
- `dbs` package:
– AbstractDatabase interface (`abstract_db.py`).
– Concrete schemas (`dbs/v1/db.py`).
- Decryption subsystem:
– Python wrapper (`decryption/dbs/.../decrypt14_15.py`)
– Java utilities under utils/ within that folder.
E. External & OS Resources
- WhatsApp DB file(s) on disk (`msgstore.db`, `msgstore.db.cryptX`, `wa.db`).
- Local media directory.
- Third-party libs: Kivy/KivyMD, SQLite, external decrypter.

##### Relationships & Data Flows
- User clicks UI element → Controller receives event → Controller invokes Model method →
Model calls either:
– Decryption module (if DB encrypted) → yields decrypted DB file
– DB schema loader (`dbs`) → queries SQLite → returns raw data
→ Model formats into viewable objects → Controller passes to View → View renders.
- Utility/observer.py may broadcast changes (e.g., DB loaded) to interested components.
- Assets (images/fonts) are referenced by the View at runtime.

##### Architectural Patterns & Principles
- MVC (Model-View-Controller) clear separation.
- Plugin-style schema loading (dynamic discovery of `dbs/v*` packages).
- Observer pattern (Utility/observer.py) for decoupled event propagation.

##### Essential Details to Capture
- Entry point (`main.py`) and app initialization.
- ScreenManager switching among screens.
- One-to-one mapping of Controller ↔ Model ↔ View screens.
- Observer utility broadcasting DB-loaded or schema-added events.
- Assets directory feeding media previews.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    main["main.py\n(App Init & ScreenManager)"]:::ui
    click main "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/main.py"

    %% UI Layer
    subgraph "UI Layer"
        screens_py["screens.py"]:::ui
        base_screen["base_screen.py"]:::ui
        LoginView["LoginScreen\n(login_screen.py)"]:::ui
        LoginKV["login_screen.kv"]:::ui
        AboutKV["about.kv"]:::ui
        SettingsKV["settings.kv"]:::ui
        MainView["MainScreen\n(main_screen.py)"]:::ui
        MainKV["main_screen.kv"]:::ui
        ChatView["ChatScreen\n(chat_screen.py)"]:::ui
        ChatKV["chat_screen.kv"]:::ui
        TemplateView["TemplateScreen\n(template_screen.py)"]:::ui
        Components["Components (.kv widgets)"]:::ui
    end
    click screens_py "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/screens.py"
    click base_screen "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/base_screen.py"
    click LoginView "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/LoginScreen/login_screen.py"
    click LoginKV "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/LoginScreen/login_screen.kv"
    click AboutKV "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/LoginScreen/about.kv"
    click SettingsKV "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/LoginScreen/settings.kv"
    click MainView "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/MainScreen/main_screen.py"
    click MainKV "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/MainScreen/main_screen.kv"
    click ChatView "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/ChatScreen/chat_screen.py"
    click ChatKV "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/View/ChatScreen/chat_screen.kv"
    click Components "https://github.com/voice-less/whatsapp-msgstore-viewer/tree/main/View/components/"

    %% Controllers Layer
    subgraph "Controller Layer"
        LoginCtrl["login_screen.py"]:::controller
        MainCtrl["main_screen.py"]:::controller
        ChatCtrl["chat_screen.py"]:::controller
        TemplateCtrl["template_screen.py"]:::controller
    end
    click LoginCtrl "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Controller/login_screen.py"
    click MainCtrl "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Controller/main_screen.py"
    click ChatCtrl "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Controller/chat_screen.py"
    click TemplateCtrl "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Controller/template_screen.py"

    %% Models Layer
    subgraph "Model Layer"
        BaseModel["base_model.py"]:::model
        LoginModel["login_screen.py"]:::model
        MainModel["main_screen.py"]:::model
        ChatModel["chat_screen.py"]:::model
        TemplateModel["template_screen.py"]:::model
    end
    click BaseModel "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Model/base_model.py"
    click LoginModel "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Model/login_screen.py"
    click MainModel "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Model/main_screen.py"
    click ChatModel "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Model/chat_screen.py"
    click TemplateModel "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Model/template_screen.py"

    %% Data Layer
    subgraph "Data Layer"
        subgraph "Database Abstraction"
            AbstractDB["abstract_db.py"]:::data
            SchemaV1["v1/db.py"]:::data
        end
        subgraph "Decryption Subsystem"
            DecryptWrapper["decrypt14_15.py"]:::data
            DecryptUtils["utils/"]:::data
            DecryptEntry["decrypt_db.py"]:::data
        end
    end
    click AbstractDB "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/dbs/abstract_db.py"
    click SchemaV1 "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/dbs/v1/db.py"
    click DecryptWrapper "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/decryption/dbs/WhatsAppCrypt14Crypt15Decrypter/decrypt14_15.py"
    click DecryptUtils "https://github.com/voice-less/whatsapp-msgstore-viewer/tree/main/decryption/dbs/WhatsAppCrypt14Crypt15Decrypter/utils/"
    click DecryptEntry "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/decryption/dbs/decrypt_db.py"

    %% Utility & External
    subgraph "Utilities & External"
        Utils["Utils.py"]:::utility
        Observer["observer.py"]:::utility
        AssetsFonts["EmojiOneColor.otf"]:::external
        AssetsImages["images/"]:::external
        AboutAssets["about/"]:::external
        Requirements["requirements.txt"]:::external
        DecryptReq["requirements.txt"]:::external
        Libs["libs/"]:::external
        Filesystem["WhatsApp DB & Media\n(msgstore.db, wa.db, media)"]:::external
        ThirdParty["Kivy/KivyMD, SQLite, External Decrypter"]:::external
    end
    click Utils "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Utility/Utils.py"
    click Observer "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/Utility/observer.py"
    click AssetsFonts "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/assets/fonts/EmojiOneColor.otf"
    click AssetsImages "https://github.com/voice-less/whatsapp-msgstore-viewer/tree/main/assets/images/"
    click AboutAssets "https://github.com/voice-less/whatsapp-msgstore-viewer/tree/main/about/"
    click Requirements "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/requirements.txt"
    click DecryptReq "https://github.com/voice-less/whatsapp-msgstore-viewer/blob/main/decryption/dbs/WhatsAppCrypt14Crypt15Decrypter/requirements.txt"
    click Libs "https://github.com/voice-less/whatsapp-msgstore-viewer/tree/main/libs/"

    %% Relationships
    main -->|initializes| screens_py
    screens_py -->|inherits| base_screen
    main -->|loads| LoginView
    main -->|loads| MainView
    main -->|loads| ChatView
    main -->|loads| TemplateView

    LoginView -->|user event| LoginCtrl
    MainView -->|user event| MainCtrl
    ChatView -->|user event| ChatCtrl
    TemplateView -->|user event| TemplateCtrl

    LoginCtrl -->|uses| LoginModel
    MainCtrl -->|uses| MainModel
    ChatCtrl -->|uses| ChatModel
    TemplateCtrl -->|uses| TemplateModel

    LoginModel -->|reads/writes| AbstractDB
    MainModel -->|reads/writes| AbstractDB
    ChatModel -->|reads/writes| AbstractDB
    TemplateModel -->|reads/writes| AbstractDB

    AbstractDB -->|loads schema| SchemaV1
    LoginModel -->|decrypts if needed| DecryptEntry
    MainModel -->|decrypts if needed| DecryptEntry
    ChatModel -->|decrypts if needed| DecryptEntry
    TemplateModel -->|decrypts if needed| DecryptEntry

    DecryptEntry -->|wraps| DecryptWrapper
    DecryptWrapper -->|calls| DecryptUtils

    LoginModel -->|formats data| LoginCtrl
    MainModel -->|formats data| MainCtrl
    ChatModel -->|formats data| ChatCtrl
    TemplateModel -->|formats data| TemplateCtrl

    LoginCtrl -->|updates| LoginView
    MainCtrl -->|updates| MainView
    ChatCtrl -->|updates| ChatView
    TemplateCtrl -->|updates| TemplateView

    %% Observer Pattern
    AbstractDB -->|notifies| Observer
    SchemaV1 -->|notifies| Observer
    Observer -->|broadcasts| LoginCtrl
    Observer -->|broadcasts| MainCtrl
    Observer -->|broadcasts| ChatCtrl

    %% Assets & External
    LoginView -->|loads| AssetsImages
    ChatView -->|loads| AssetsImages
    MainView -->|loads| AssetsImages
    AllViews(("All Views")) -->|uses fonts| AssetsFonts
    AbstractDB -->|accesses files| Filesystem
    DecryptEntry -->|reads encrypted files| Filesystem
    AllViews -->|relies on| ThirdParty

    classDef ui fill:#CCDDFF,stroke:#333,stroke-width:1px
    classDef controller fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef model fill:#FFDD99,stroke:#333,stroke-width:1px
    classDef data fill:#FFCC00,stroke:#333,stroke-width:1px
    classDef utility fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
```
