# pyca/bcrypt architecture

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

- Interactive diagram: https://gitdiagram.com/pyca/bcrypt
- Repository: https://github.com/pyca/bcrypt

## Overview

##### Main Components
- Python API Layer: This is represented by the "bcrypt" directory (src/bcrypt) that exposes functions like hashpw, gensalt, checkpw, and kdf. It defines the library’s public interface.
- Rust Extension Module: Located in src/_bcrypt, these files (Cargo.toml, Cargo.lock, lib.rs, and associated Rust module files) implement the core functionality (the cryptographic operations) in Rust. This parts of the system are built as a Python extension.
- Build/Configuration and Packaging: Files such as pyproject.toml, noxfile.py, MANIFEST.in, release.py, and requirements.txt are involved in building, testing, and packaging the library. They coordinate the setup, compilation with the Rust compiler (and C compiler if required for CFFI aspects), and distribution (wheels and source distributions).
- Continuous Integration & Deployment (CI/CD): The .github/workflows directory includes CI scripts for running tests, building wheels for various platforms, and publishing to PyPI. This outlines the automated workflows that enforce quality and compatibility.
- Tests: The tests directory with test_bcrypt.py confirms that the public API works as intended and that password verification functions operate correctly.

##### Establish Relationships and Interactions
- When a user calls a function from the Python API (in src/bcrypt), the call is delegated to the Rust extension (from src/_bcrypt) for performing the cryptographic hash.
- The build system (triggered by noxfile.py and configuration in pyproject.toml) compiles the Rust code via Cargo integration, and then packages it alongside the Python modules.
- CI/CD pipelines use GitHub workflows to run tests, build artifacts (including manylinux wheels), and deploy to PyPI.
- There is a direct dependency where the Python API relies on the Rust implementation for performance and security, and automated testing ensures this integration remains consistent.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The design clearly separates the public-facing API (idiomatic Python) from the performance-intensive cryptographic implementation in Rust.
- Modularization: The division into multiple directories (src, tests, .github) reflects a modular approach, ensuring that each aspect like core logic, testing, and deployment is maintained independently.
- Build/Release Automation: The integration of CI workflows and build scripts emphasizes continuous integration and automated deployment practices.
- Security Focus: Since the library is used for hashing passwords, clear design segments ensure that the Rust module (where security-critical code resides) is isolated and well-tested.

##### Final Advice
- Although the primary focus is on the password hashing functionality, include pointers (or annotations) regarding security measures and version compatibilities (as mentioned in the README).
- Role of the automated tests and deployment workflows to assure quality and maintain compatibility across different Python and platform versions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    A["User/Client (Python Program)"]:::client

    %% Python API Layer
    subgraph "Python API Layer"
        B1["Directory: 'bcrypt'"]:::pythonAPI
        B2["File: '__init__.py'"]:::pythonAPI
        B1 -->|"contains"| B2
    end

    %% Rust Extension Module
    subgraph "Rust Extension Module"
        C1["Directory: '_bcrypt'"]:::rust
        C2["Cargo.toml"]:::rust
        C3["Cargo.lock"]:::rust
        C4["lib.rs"]:::rust
        C1 --> C2
        C1 --> C3
        C1 --> C4
    end

    %% Build/Packaging System
    subgraph "Build/Packaging System"
        D1["pyproject.toml"]:::build
        D2["noxfile.py"]:::build
        D3["MANIFEST.in"]:::build
        D4["release.py"]:::build
        D5["requirements.txt"]:::build
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        E1["ci.yml"]:::ci
        E2["lock.yml"]:::ci
        E3["pypi-publish.yml"]:::ci
        E4["wheel-builder.yml"]:::ci
    end

    %% Test Suite
    subgraph "Test Suite"
        F1["test_bcrypt.py"]:::test
    end

    %% Core Flow Connections
    A -->|"calls"| B1
    B1 -->|"delegates cryptographic operations"| C1

    %% Build Process Connections (using D1 as representative file)
    D1 ---|"builds"| B1
    D1 ---|"builds"| C1
    D1 ---|"triggers"| E1

    %% CI/CD Testing Connection
    E1 ---|"runs tests"| F1

    %% Styles
    classDef client fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef pythonAPI fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef rust fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef build fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef ci fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef test fill:#f8d7da,stroke:#721c24,stroke-width:2px;

    %% Click Events for Python API Layer
    click B1 "https://github.com/pyca/bcrypt/tree/main/src/bcrypt"
    click B2 "https://github.com/pyca/bcrypt/blob/main/src/bcrypt/__init__.py"

    %% Click Events for Rust Extension Module
    click C1 "https://github.com/pyca/bcrypt/tree/main/src/_bcrypt"
    click C2 "https://github.com/pyca/bcrypt/blob/main/src/_bcrypt/Cargo.toml"
    click C3 "https://github.com/pyca/bcrypt/blob/main/src/_bcrypt/Cargo.lock"
    click C4 "https://github.com/pyca/bcrypt/blob/main/src/_bcrypt/src/lib.rs"

    %% Click Events for Build/Packaging System
    click D1 "https://github.com/pyca/bcrypt/blob/main/pyproject.toml"
    click D2 "https://github.com/pyca/bcrypt/blob/main/noxfile.py"
    click D3 "https://github.com/pyca/bcrypt/blob/main/MANIFEST.in"
    click D4 "https://github.com/pyca/bcrypt/blob/main/release.py"
    click D5 "https://github.com/pyca/bcrypt/blob/main/requirements.txt"

    %% Click Events for CI/CD Pipeline
    click E1 "https://github.com/pyca/bcrypt/blob/main/.github/workflows/ci.yml"
    click E2 "https://github.com/pyca/bcrypt/blob/main/.github/workflows/lock.yml"
    click E3 "https://github.com/pyca/bcrypt/blob/main/.github/workflows/pypi-publish.yml"
    click E4 "https://github.com/pyca/bcrypt/blob/main/.github/workflows/wheel-builder.yml"

    %% Click Event for Test Suite
    click F1 "https://github.com/pyca/bcrypt/blob/main/tests/test_bcrypt.py"
```
