# protonpass/proton-pass-common architecture

> Architecture diagram of the GitHub repository protonpass/proton-pass-common, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/protonpass/proton-pass-common
- Repository: https://github.com/protonpass/proton-pass-common

## Overview

##### Project Type and Purpose
- The project is a multi-crate Rust repository that provides a common library for handling password management, authentication (including TOTP generation, two-factor authentication, and parsing from various formats), and related utilities.
- It is designed to be shared across multiple clients – mobile (Android and iOS) and web – by exposing the core functionality via platform-specific “glue” modules. The README clearly describes the three main modules:
- proton-pass-common (the core pure-Rust logic and tests)
- proton-pass-mobile (glue code for mobile, using UniFFI to export the Rust library to Android and iOS)
- proton-pass-web (glue code for web clients, primarily via wasm-pack)

##### File Structure
- Top-level directories (e.g., proton-pass-common, proton-pass-mobile, proton-pass-web, proton-pass-totp, proton-authenticator, etc.) indicate that the repository is organized as a multi-crate workspace.
- Within mobile, there are platform-specific subdirectories (“android” and “iOS”) with their own build scripts, native configuration files (e.g., AndroidManifest.xml, iOS Swift package files), and binding generation tools (e.g., Makefile targets for kotlin and swift bindings).
- The common module is purely Rust and includes extensive source files and tests, suggesting a functional separation where the core business logic is isolated from the platform-specific layers.
- There are also helper tools (in the “tools” directory) for generating domain files and customized lists, which might be used during the build or release process.
- Configuration files (Cargo.toml, Makefile, rustfmt.toml) help manage builds, formatting, linting, and dependency releases.

##### README for Additional Insights
- The README details the workflow for adding functions to the library and clearly defines the steps to maintain consistency across the common, mobile, and web modules.
- Instructions for building across Android (using NDK and target configuration), iOS (using Swift Packages and xcframeworks), and web (using wasm-pack) indicate that the “glue” layers are crucial connectors between the core library and target clients.
- The project uses modern tools like UniFFI (for mobile binding generation) and wasm-pack (for web distribution), which are important to note in the architecture.

a. Main Components to Include:
- Proton Pass Common:
– Represents the central core library implemented in Rust.
– Contains key functions for encryption, TOTP generation, parsing different authentication formats, and other password management utilities.
- Proton Pass Mobile:
– Split into Android and iOS submodules.
– Both submodules utilize the core Proton Pass Common library by calling its functions.
– Include portions for platform-specific binding generation (UniFFI), including gradle build scripts and Swift Package integration.
- Proton Pass Web:
– Contains glue code to expose the core functions to JavaScript via wasm-bindgen and wasm-pack.
- Additional Components (Optional):
– Proton Pass Totp and other related modules that might be used as separate crates for specialized functionality.
– Testing and build automation components such as the Makefile, cargo configurations, and tooling scripts.

b. Relationships and Interactions:
- Within the mobile module, show a split between Android and iOS. Illustrate that both use UniFFI as a binding generator to expose Rust functions to the native language environments.
- That the web module interfaces via WASM bindings and that data flows from the web UI to the common library’s backend logic.

c. Important Architectural Patterns and Design Principles:
- Separation of Concerns – the core functionality is fully isolated in the common library, and platform-specific implementations are kept in separate modules.
- Language Bindings – use of UniFFI for mobile and wasm-bindgen for web to separate the cross-language boundary and enable reuse of the core logic.
- Multi-crate Workspace – the repository structure supports independent testing, building, and deployment of each module.
- Testing Centralization – only the common library includes dedicated Rust tests, emphasizing the need to rigorously verify core functionality.

d. Relevant Technologies and Frameworks:
- Rust and Cargo (for package and dependency management).
- UniFFI – used in mobile modules for creating native bindings

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Services
    subgraph "Core Services"
        PPCommon["Proton Pass Common"]:::common
        PPTotp["Proton Pass Totp"]:::totp
    end

    %% Mobile Modules
    subgraph "Mobile Modules"
        PM["Proton Pass Mobile"]:::mobile
        Android["Android Module"]:::mobile
        iOS["iOS Module"]:::mobile
        UniFFI["UniFFI Binding Generation"]:::uniffi
    end

    %% Web Module
    subgraph "Web Module"
        PPWeb["Proton Pass Web"]:::web
    end

    %% Connections for Mobile
    PM -->|"contains"| Android
    PM -->|"contains"| iOS
    Android -->|"viaUniFFI"| UniFFI
    iOS -->|"viaUniFFI"| UniFFI
    UniFFI -->|"exposes"| PPCommon

    %% Web connection
    PPWeb -->|"bindsTo"| PPCommon

    %% Totp relationship
    PPCommon -->|"utilizes"| PPTotp

    %% Click Events
    click PPCommon "https://github.com/protonpass/proton-pass-common/tree/main/proton-pass-common/"
    click PM "https://github.com/protonpass/proton-pass-common/tree/main/proton-pass-mobile/"
    click PPWeb "https://github.com/protonpass/proton-pass-common/tree/main/proton-pass-web/"
    click PPTotp "https://github.com/protonpass/proton-pass-common/tree/main/proton-pass-totp/"
    click UniFFI "https://github.com/protonpass/proton-pass-common/blob/main/proton-pass-mobile/uniffi.toml"

    %% Styles
    classDef common fill:#DDEEFF,stroke:#333,stroke-width:2px;
    classDef mobile fill:#FFDDEE,stroke:#333,stroke-width:2px;
    classDef web fill:#DFFFD6,stroke:#333,stroke-width:2px;
    classDef totp fill:#FFEFD6,stroke:#333,stroke-width:2px;
    classDef uniffi fill:#FFF0F5,stroke:#333,stroke-width:2px;
```
