# nordsecurity/libdrop architecture

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

- Interactive diagram: https://gitdiagram.com/nordsecurity/libdrop
- Repository: https://github.com/nordsecurity/libdrop

## Overview

##### Project Type and Purpose
- libdrop is a **modular Rust library** for peer-to-peer and WAN file transfers over meshnets, with a **CLI/server example** (`udrop`) and **multi-language bindings** via UniFFI.
- It’s not a traditional “microservices” deployment but a **collection of inter-dependent crates** (modules) that compose the core library plus example services and binding tools.

##### File Structure
- **drop-core**: Core domain types & logic (status, events).
- **drop-config**: Configuration loader/validator.
- **drop-auth**: HTTP auth layer for clients/servers.
- **drop-storage**: Database layer (PostgreSQL migrations, sync, types).
- **drop-transfer**: Transfer engine (protocol v6, WS client/server, file I/O, manager, tasks).
- **drop-analytics**: Instrumentation & analytics hooks.
- **norddrop**: CLI/UDL layer for UniFFI, exposes `norddrop_version()`, config, device interfaces.
- **uniffi-bindgen** & **contrib/swift_package**/**bindings**: Binding-generation utilities (Python, Swift).
- **udrop example** (in `drop-transfer/examples/udrop.rs` and `run.py server`): Illustrative server/client binaries.
- **test/**: Scenario-based Python test harness orchestrating containerized end-to-end tests.

##### README for Insights
- **Example server** spun up via `run.py server run` in a Docker container.
- **Client example** via `cargo run --example udrop`.
- **Database** is external (PostgreSQL) with migrations in `drop-storage`.

##### Main Components & Relationships
A. **Frontend/CLI**
– Components: `norddrop` CLI, `udrop` client binary, Python test harness.
– Interacts with drop-transfer (over TCP/WS) or drop-auth (HTTP).
B. **Transfer Service**
– `drop-transfer` WS server & protocol v6 listener.
– Exposes TCP/WS endpoints for incoming file streams.
– Depends on: drop-auth (to authenticate), drop-storage (to persist events/metadata), drop-core (domain logic), drop-analytics (emit metrics).
C. **Authentication Layer**
– `drop-auth` HTTP endpoints for login/permission tokens.
– Used by both client and server to secure transfers.
D. **Storage Layer**
– `drop-storage` crate + PostgreSQL instance.
– Responsibilities: schema migrations, message/event persistence, retry/sync cleanup.
E. **Core Library**
– `drop-core` central types (status, event definitions) used by all other crates.
F. **Configuration & Analytics**
– `drop-config` loads YAML/ENV parameters.
– `drop-analytics` instrumentation shims embedded in transfer/auth.
G. **Binding Generation**
– `uniffi-bindgen` + `contrib` scripts generate language bindings (Swift, Python).
– Produces multi-language library wrappers for embedding in mobile/desktop apps.
H. **External Services**
– **PostgreSQL database** (for drop-storage).
– **Moose tracker** (peer discovery over meshnet).

##### Architectural Patterns & Design Principles
- **Module decomposition**: Each crate encapsulates a clear responsibility (Single Responsibility Principle).
- **Layered architecture**:
– Presentation (CLI/test harness)
– Application (transfer, auth, analytics)
– Domain (core)
– Infrastructure (storage/DB, config)
- **Asynchronous event-driven flows** in `drop-transfer`: use tasks/manager to orchestrate transfers.
- **Protocol isolation**: Network protocols (v6, WS) abstracted under `protocol/` submodule.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend/CLI Layer
    subgraph "Frontend / CLI" 
        direction TB
        Norddrop["norddrop CLI"]:::frontend
        Udrop["udrop Client Example"]:::frontend
        TestHarness["Python Test Harness"]:::frontend
    end

    %% Application Services Layer
    subgraph "Application Services"
        direction TB
        Transfer["drop-transfer Service\n(WebSocket v6, TCP)"]:::service
        Auth["drop-auth HTTP Auth"]:::service
    end

    %% Libraries & Config Layer
    subgraph "Core & Infrastructure Libraries"
        direction TB
        Core["drop-core Library"]:::core
        Config["drop-config Loader"]:::infra
        Analytics["drop-analytics Instrumentation"]:::infra
        Storage["drop-storage Layer\n(PostgreSQL migrations)"]:::infra
    end

    %% Binding Generation Tools
    subgraph "Binding Generation Tools"
        direction TB
        UffiBindgen["uniffi-bindgen"]:::binding
        PyBindings["generate_bindings.py"]:::binding
        SwiftPkg["Swift Package"]:::binding
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Postgres[(PostgreSQL DB)]:::external
        Moose[(Moose Tracker)]:::external
    end

    %% Relationships
    Norddrop -->|HTTP/API| Auth
    Norddrop -->|WS/TCP| Transfer
    Udrop -->|WS/TCP| Transfer
    TestHarness -->|HTTP/WS| Transfer
    TestHarness -->|HTTP| Auth

    Transfer -->|auth checks| Auth
    Transfer -->|persist events| Storage
    Transfer -->|emit metrics| Analytics
    Transfer -->|uses types| Core

    Auth -->|uses types| Core
    Storage -->|uses types| Core
    Config -->|provides config| Transfer
    Config -->|provides config| Auth
    Analytics -->|embedded in| Transfer
    Analytics -->|embedded in| Auth

    Storage -->|runs migrations| Postgres
    Transfer -->|"WebSocket v6"| Moose

    UffiBindgen -->|generates UDL| Norddrop
    UffiBindgen -->|generates bindings| PyBindings
    UffiBindgen -->|generates bindings| SwiftPkg

    %% Click Events
    click Norddrop "https://github.com/nordsecurity/libdrop/blob/main/norddrop/Cargo.toml"
    click Udrop "https://github.com/nordsecurity/libdrop/blob/main/drop-transfer/examples/udrop.rs"
    click TestHarness "https://github.com/nordsecurity/libdrop/blob/main/test/run.py"
    click Transfer "https://github.com/nordsecurity/libdrop/blob/main/drop-transfer/Cargo.toml"
    click Auth "https://github.com/nordsecurity/libdrop/blob/main/drop-auth/Cargo.toml"
    click Storage "https://github.com/nordsecurity/libdrop/blob/main/drop-storage/Cargo.toml"
    click Core "https://github.com/nordsecurity/libdrop/blob/main/drop-core/Cargo.toml"
    click Config "https://github.com/nordsecurity/libdrop/blob/main/drop-config/Cargo.toml"
    click Analytics "https://github.com/nordsecurity/libdrop/blob/main/drop-analytics/Cargo.toml"
    click UffiBindgen "https://github.com/nordsecurity/libdrop/blob/main/uniffi-bindgen/Cargo.toml"
    click PyBindings "https://github.com/nordsecurity/libdrop/blob/main/bindings/generate_bindings.py"
    click SwiftPkg "https://github.com/nordsecurity/libdrop/blob/main/contrib/swift_package/Package.swift"

    %% Classes
    classDef frontend fill:#FFE4B5,stroke:#CC8400,stroke-width:2px
    classDef service fill:#E0FFFF,stroke:#008B8B,stroke-width:2px
    classDef core fill:#ADD8E6,stroke:#00008B,stroke-width:2px
    classDef infra fill:#98FB98,stroke:#006400,stroke-width:2px
    classDef binding fill:#FFFACD,stroke:#DAA520,stroke-width:2px
    classDef external fill:#D3D3D3,stroke:#696969,stroke-width:2px
```
