# tencent/mmkv architecture

> Architecture diagram of the GitHub repository tencent/mmkv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tencent/mmkv
- Repository: https://github.com/tencent/mmkv

## Overview

##### Project type and purpose
- This is an **open-source, cross-platform key-value storage library** (“MMKV”) implemented in C++ (“Core”) and exposed on multiple platforms (Android, iOS/macOS, Windows, POSIX, HarmonyOS), with language/interface bindings (Java, Objective-C/Swift, C#, Python, Dart, JavaScript/TypeScript).
- Purpose: ultra-fast, memory-mapped key-value store for mobile/desktop/native apps, used by WeChat and others.

##### File structure
- Top-level “Core” directory: pure C++ engine (memory‐map handling, protobuf encoding, process locks, CRC, AES).
- Per-platform folders:
- Android/MMKV & mmkvannotation & mmkvdemo (Java API, JNI glue, CMake build, demos)
- iOS/MMKV & MMKVDemo (Objective-C++ static/dynamic libs, Xcode projects, demo apps)
- Win32 (Visual Studio solution, demos)
- POSIX (CMake, C++ shared/static lib, Go bridge, demo)
- OpenHarmony (TS/ETS frontends, N-API/native bridge, CMake)
- Python (pybind11 wrapper, setup.py, demo)
- Flutter & flutter plugins (Dart API, platform channels, native code for iOS/Android/OhOS)
- Build scripts and packaging: CMakeLists, Gradle (.gradle/, settings.gradle), Podspec, hvigorfile.ts, Makefile, Dockerfile.

##### README for additional insights
- Confirms multi-platform support, core features (mmap + protobuf), multi-process concurrency, per-platform installation steps, demos/tutorials.

##### Diagramming conventions
- Green for Core
- Blue for platform bindings
- Orange for client/demo apps
- Gray for build tools & OS services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        Core["MMKV Core (C++ Engine)"]:::core
        MemFile["MemoryFile"]:::core
        ProtobufCoder["MiniPBCoder"]:::core
        IPC["InterProcessLock"]:::core
        Core --> MemFile
        Core --> ProtobufCoder
        Core --> IPC
    end

    %% Platform Bindings
    subgraph "Platform Bindings"
        direction TB
        Android["Android JNI + Java API"]:::binding
        iOS["iOS Objective-C++ Pod + Swift/Obj-C API"]:::binding
        Windows["Windows C++ DLL/Lib + C++ API"]:::binding
        POSIX["POSIX C++ Library + C++ API"]:::binding
        Python["Python pybind11 Module"]:::binding
        Flutter["Flutter/Dart Plugin"]:::binding
        OH["OpenHarmony JS/TS Frontend + Native Bridge"]:::binding
    end

    %% Demo/Example Apps
    subgraph "Demo/Example Apps"
        direction TB
        AndroidDemo["Android Demo App"]:::demo
        iOSDemo["iOS Demo Apps"]:::demo
        WindowsDemo["Windows Demo App"]:::demo
        POSIXDemo["POSIX Demo"]:::demo
        PythonDemo["Python Demo"]:::demo
        FlutterExample["Flutter Example App"]:::demo
        OHExample["OpenHarmony Example App"]:::demo
    end

    %% Build Tools
    subgraph "Build & Deploy Tools"
        direction TB
        BuildTools["CMake, Gradle, Podspec, Makefile, Docker, hvigor"]:::tools
    end

    %% OS Services
    subgraph "OS Services & Libraries"
        direction TB
        FileSys[(File System / mmap)]:::os
        ProtobufLib[(Protobuf Library)]:::os
        SysLock[(System Locks)]:::os
    end

    %% Connections: bindings to core
    Android -->|"wraps"| Core
    iOS -->|"wraps"| Core
    Windows -->|"wraps"| Core
    POSIX -->|"wraps"| Core
    Python -->|"wraps"| Core
    Flutter -->|"wraps"| Core
    OH -->|"wraps"| Core

    %% Demos link to bindings
    AndroidDemo -->|uses| Android
    iOSDemo -->|uses| iOS
    WindowsDemo -->|uses| Windows
    POSIXDemo -->|uses| POSIX
    PythonDemo -->|uses| Python
    FlutterExample -->|uses| Flutter
    OHExample -->|uses| OH

    %% Core to OS services
    Core -->|uses| FileSys
    Core -->|uses| ProtobufLib
    Core -->|uses| SysLock

    %% Build tools produce bindings
    BuildTools -.->|build| Android
    BuildTools -.->|build| iOS
    BuildTools -.->|build| Windows
    BuildTools -.->|build| POSIX
    BuildTools -.->|build| Python
    BuildTools -.->|build| Flutter
    BuildTools -.->|build| OH

    %% Click Events
    click Core "https://github.com/tencent/mmkv/tree/master/Core/"
    click Android "https://github.com/tencent/mmkv/tree/master/Android/MMKV/mmkv/"
    click AndroidDemo "https://github.com/tencent/mmkv/tree/master/Android/MMKV/mmkvdemo/"
    click iOS "https://github.com/tencent/mmkv/tree/master/iOS/MMKV/MMKV/"
    click iOSDemo "https://github.com/tencent/mmkv/tree/master/iOS/MMKVDemo/MMKVDemo/"
    click Windows "https://github.com/tencent/mmkv/tree/master/Win32/"
    click WindowsDemo "https://github.com/tencent/mmkv/tree/master/Win32/"
    click POSIX "https://github.com/tencent/mmkv/tree/master/POSIX/src/"
    click POSIXDemo "https://github.com/tencent/mmkv/tree/master/POSIX/demo/"
    click Python "https://github.com/tencent/mmkv/tree/master/Python/"
    click PythonDemo "https://github.com/tencent/mmkv/blob/master/Python/demo.py"
    click Flutter "https://github.com/tencent/mmkv/tree/master/flutter/mmkv/"
    click FlutterExample "https://github.com/tencent/mmkv/tree/master/flutter/mmkv/example/"
    click OH "https://github.com/tencent/mmkv/tree/master/OpenHarmony/MMKV/"
    click OHExample "https://github.com/tencent/mmkv/tree/master/OpenHarmony/entry/"

    %% Styles
    classDef core fill:#9f6,stroke:#333,stroke-width:1px
    classDef binding fill:#6cf,stroke:#333,stroke-width:1px
    classDef demo fill:#f96,stroke:#333,stroke-width:1px
    classDef tools fill:#ccc,stroke:#333,stroke-width:1px
    classDef os fill:#ddd,stroke:#333,stroke-width:1px
```
