# safing/portmaster architecture

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

- Interactive diagram: https://gitdiagram.com/safing/portmaster
- Repository: https://github.com/safing/portmaster

## Overview

##### Project Type and Purpose

**Project Type:**
Portmaster is a **full-stack application** that functions as an **open-source application firewall**. It integrates deeply with the operating system's network stack to provide privacy controls, monitoring, and blocking capabilities for both Windows and Linux desktops.

**Purpose:**
Portmaster aims to enhance user privacy by monitoring all network activity, blocking unwanted trackers and malware, managing secure DNS settings, recording network history, and utilizing the Safing Privacy Network (SPN) for enhanced privacy through encrypted routing.

##### File Structure

**Top-Level Directories:**
- **`desktop`**
- Contains the **frontend** built with **Angular** and integrates with **Tauri** for cross-platform desktop functionality.
- **`service`**
- Houses the **backend services** written in **Go**, managing network interception, configurations, and interactions with the OS.
- **`spn`**
- Manages the **Safing Privacy Network**, including modules for network routing and privacy enhancements.
- **`windows_kext` & `windows_core_dll`**
- Contain **Windows kernel extensions** and **DLLs** necessary for deep integration with the Windows network stack.
- **`base`, `cmds`, `packaging`, `runtime`**
- Support various aspects of the application, including core functionalities, command-line tools, packaging scripts for different OS environments, and runtime configurations.

**Architectural Indicators:**
- **Modular Structure:** Clear separation between frontend (`desktop/angular`), backend (`service`, `base`), and specialized modules (`spn`).
- **Configuration and Build Scripts:** Presence of `.github`, `Earthfile`, and various `Makefile` and `Dockerfile` scripts indicate a robust CI/CD pipeline and environment setup.
- **Kernel Integration:** Directories like `windows_kext` suggest deep OS-level integration for network packet interception.

##### README for Additional Insights

The README outlines the following key architectural and technological aspects:
- **Integration with Network Stack:** Uses `nfqueue` on Linux and Windows Filtering Platform (WFP) drivers on Windows for packet interception.
- **Local Processing:** Emphasizes that all processing is done locally, enhancing privacy.
- **Update Mechanisms:** Automatic, signed updates ensure security and ease of maintenance.
- **User Interface:** Utilizes Electron (with plans to transition away) and Tauri for the desktop UI, providing both user-friendly and browser-based interfaces.
- **SPN Integration:** Incorporates the Safing Privacy Network for encrypted routing, positioned between traditional VPNs and Tor.

##### a. Main Components
- **Frontend/UI:**
- **Angular Application:** Located in `desktop/angular`, serving the user interface.
- **Tauri/Electron Integration:** Facilitates cross-platform desktop functionalities.

- **Backend Services:**
- **Go Services:** Located in `service` and `base`, handling business logic, network interception, and configuration management.

- **Kernel Extensions/Drivers:**
- **Windows Kexts:** Found in `windows_kext` and `windows_core_dll`, enabling low-level network packet interception on Windows.
- **eBPF Modules:** For Linux network interception.

- **Safing Privacy Network (SPN):**
- **SPN Modules:** Located in the `spn` directory, managing encrypted routing and privacy features.

- **Database:**
- **Local Databases:** For storing network activity logs, configurations, and usage data.

- **Configuration & Update Mechanisms:**
- **Earthly & Docker:** For build and deployment workflows.
- **Automatic Update Services:** Ensuring the application and its components remain up-to-date securely.

##### b. Relationships and Interactions
- **UI ↔ Backend Services:**
- The Angular frontend communicates with Go backend services via RESTful APIs or WebSockets for real-time updates.

- **Backend ↔ Kernel Extensions:**
- Backend services interact with kernel drivers (WFP on Windows, eBPF on Linux) to intercept and manage network packets.

- **Backend ↔ SPN:**
- Services route traffic through the SPN modules for encrypted and privacy-enhanced communication.

- **Backend ↔ Database:**
- All configuration settings, network logs, and usage data are stored and retrieved from local databases.

- **Update Mechanism ↔ All Components:**
- Automatic update services ensure that the frontend, backend, kernel drivers, and SPN modules receive the latest updates.

##### c. Architectural Patterns or Design Principles
- **Modular Architecture:**
- Separation of concerns with distinct modules for frontend, backend, kernel integration, and privacy networking.

- **Microservices:**
- Backend services are likely structured as microservices, each handling specific functionalities like network interception, configuration management, and SPN routing.

- **Local-First Design:**
- Emphasis on all processing being local enhances privacy and security.

- **Extensibility:**
- Modular components allow for future enhancements, such as transitioning away from Electron to more lightweight UI frameworks.

##### d. Relevant Technologies, Frameworks, or Libraries
- **Frontend:**
- **Angular:** For building dynamic and responsive user interfaces.
- **Tauri/Electron:** For cross-platform desktop application capabilities.

- **Backend:**
- **Go (Golang):** For efficient and concurrent backend services.
- **eBPF (Linux) & WFP (Windows):** For deep network packet interception and manipulation.

- **Kernel Extensions:**
- **Rust/C/C++:** Likely used in `windows_kext` and related directories for building secure and performant kernel drivers.

- **Databases:**
- **Local Databases:** Possibly using embedded databases like SQLite for storing logs and configurations.

- **CI/CD & Build Tools:**
- **Earthly, Docker:** For consistent build environments and deployment workflows.
- **GitHub Workflows:** For automated testing, building, and deployment processes.

##### Elements

- **Clear Labels for Each Component:**
- Frontend (Angular UI)
- Backend Services (Go Modules)
- Kernel Extensions (WFP Drivers, eBPF Modules)
- SPN Network
- Databases
- Configuration & Update Services

- From UI to Backend via APIs
- From Backend to Kernel Extensions for packet interception
- From Backend to SPN for encrypted routing
- Data storage flows between Backend and Databases
- Update flows from Update Services to all components

##### Detail and Essential Architectural Elements

- **Comprehensive Coverage:**
- Critical components are represented, including lesser-known modules and services.

- **Avoid Overcomplication:**
- While detail is essential, maintain clarity by grouping related components and using hierarchical structuring.

- **Scalability:**

- **Consistency:**

##### Final Recommendations

- **Tool Selection:**

- **Iterative Refinement:**

- **Collaborative Review:**

- **Documentation:**

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend
    subgraph Frontend
        AngularUI["Angular UI"]:::frontend
        Tauri["Tauri Desktop Integration"]:::frontend
    end

    %% Backend
    subgraph Backend
        GoServices["Go Services"]:::backend
        ConfigManagement["Configuration Management"]:::backend
        DatabaseMgmt["Database Management"]:::database
        UpdateMechanism["Update Mechanism"]:::update
        NetworkInterception["Network Interception"]:::backend
        Notifications["Notifications System"]:::notifications
    end

    %% Kernel Extensions
    subgraph Kernel_Extensions
        WindowsKexts["Windows Kexts"]:::kernel
        WindowsCoreDLLs["Windows Core DLLs"]:::kernel
        eBPF["eBPF Modules"]:::kernel
        NFQ["NFQueue Modules"]:::kernel
    end

    %% SPN
    SPN["Safing Privacy Network (SPN)"]:::spn

    %% Connections
    AngularUI -->|"Communicates via API"| GoServices
    GoServices -->|"Interacts with"| Kernel_Extensions
    GoServices -->|"Routes traffic through"| SPN
    GoServices -->|"Stores data in"| DatabaseMgmt
    UpdateMechanism -->|"Updates"| AngularUI
    UpdateMechanism -->|"Updates"| GoServices
    UpdateMechanism -->|"Updates"| Kernel_Extensions
    UpdateMechanism -->|"Updates"| SPN
    Notifications -->|"Sends notifications to"| AngularUI

    %% Click Events
    click AngularUI "https://github.com/safing/portmaster/tree/develop/desktop/angular"
    click Tauri "https://github.com/safing/portmaster/tree/develop/desktop/tauri"
    click Tauri "https://github.com/safing/portmaster/tree/develop/desktop/angular/projects/tauri-builtin"
    click GoServices "https://github.com/safing/portmaster/tree/develop/service"
    click ConfigManagement "https://github.com/safing/portmaster/tree/develop/base/config"
    click DatabaseMgmt "https://github.com/safing/portmaster/tree/develop/base/database"
    click UpdateMechanism "https://github.com/safing/portmaster/tree/develop/service/updates"
    click UpdateMechanism "https://github.com/safing/portmaster/tree/develop/base/updater"
    click UpdateMechanism "https://github.com/safing/portmaster/tree/develop/.github/workflows"
    click NetworkInterception "https://github.com/safing/portmaster/tree/develop/service/firewall/interception"
    click eBPF "https://github.com/safing/portmaster/tree/develop/service/firewall/interception/ebpf"
    click NFQ "https://github.com/safing/portmaster/tree/develop/service/firewall/interception/nfq"
    click Notifications "https://github.com/safing/portmaster/tree/develop/service/notifications"
    click Notifications "https://github.com/safing/portmaster/tree/develop/cmds/notifier"
    click WindowsKexts "https://github.com/safing/portmaster/tree/develop/windows_kext"
    click WindowsCoreDLLs "https://github.com/safing/portmaster/tree/develop/windows_core_dll"

    %% Styles
    classDef frontend fill:#1f78b4,stroke:#333,stroke-width:2px;
    classDef backend fill:#33a02c,stroke:#333,stroke-width:2px;
    classDef kernel fill:#ff7f00,stroke:#333,stroke-width:2px;
    classDef spn fill:#6a3d9a,stroke:#333,stroke-width:2px;
    classDef database fill:#ffe119,stroke:#333,stroke-width:2px;
    classDef update fill:#b15928,stroke:#333,stroke-width:2px;
    classDef notifications fill:#e31a1c,stroke:#333,stroke-width:2px;

    class AngularUI frontend
    class Tauri frontend
    class GoServices backend
    class ConfigManagement backend
    class DatabaseMgmt database
    class UpdateMechanism update
    class NetworkInterception backend
    class Notifications notifications
    class WindowsKexts kernel
    class WindowsCoreDLLs kernel
    class eBPF kernel
    class NFQ kernel
    class SPN spn
```
