# pi4j/pi4j architecture

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

- Interactive diagram: https://gitdiagram.com/pi4j/pi4j
- Repository: https://github.com/pi4j/pi4j

## Overview

##### Main Components
- API/Core Layer: Represented primarily by the “pi4j-core” module. This layer includes the primary public APIs (e.g., context creation, configuration, IO abstractions, event management, and provider registration) that users interact with.
- Native Libraries: Found in the “libraries” directory and within modules for Pi4J (for example, pi4j-library-gpiod, pi4j-library-linuxfs, and pi4j-library-pigpio). These modules encapsulate native integration (C code, Makefile-based builds, shell scripts) that support hardware communication.
- Plugin Architecture: Located in the “plugins” folder, these modules (such as pi4j-plugin-gpiod, pi4j-plugin-linuxfs, pi4j-plugin-mock, pi4j-plugin-pigpio, and pi4j-plugin-raspberrypi) dynamically extend the library with specific hardware support through well-defined extension points (e.g., by implementing provider interfaces or plugin extension services).
- Test and Distribution Modules: “pi4j-test” (for unit/integration tests) and “pi4j-distribution” (for packaging and deployment) provide additional context for how the core modules are verified and distributed.

##### Relationships and Interactions
- The API layer (pi4j-core) is the “face” of the framework and orchestrates interactions between Java applications and underlying hardware-specific implementations.
- The core uses a “context” abstraction (see the Context and ContextBuilder classes) to manage configuration and dependency injection (for example, automatically initializing provider plugins).
- The native libraries bridge the Java code to low-level hardware operations. They are invoked by the core’s wrapper/util classes to load native code and manage native resources.
- The plugin architecture acts as a “registry” for I/O providers. When a new context is built, extensions provided by modules under the plugins directory (each implementing the proper extension and provider interfaces) are dynamically discovered and registered.
- Test modules exercise the API and integration parts to ensure that created I/O interfaces (GPIO, I2C, SPI, etc.) function as intended.

##### Architectural Patterns and Design Principles
- Layered Architecture: There is a clear separation between the API, native integration, and plugin/provider implementations.
- Plugin/Extension Pattern: The use of extension and plugin mechanisms (with service loader files under META-INF/services) allows for loose coupling between the core and the various underlying hardware implementations.
- Modularity: The project’s structure (separate modules for core, libraries, plugins, tests, and distribution) emphasizes modular design and encourages independent development and deployment.
- Abstraction: Interfaces, abstract base classes, and default implementations help abstract low-level hardware details and allow “plug and play” for different hardware platforms.

##### Relevant Technologies, Frameworks, and Tools
- Java (minimum versions noted in the README – Java 11 for V2 and Java 21 for V3).
- Apache Maven for building the project.
- Native build tools (Makefiles, Shell scripts) for compiling the C code used in native libraries.
- Standard Java Service Loader mechanism (META-INF/services) for handling plugins.
- Potential use of CI/CD workflows using GitHub Actions (as seen in the “.github/workflows” folder).

- “Pi4J Core API (pi4j-core)” for context and I/O abstractions.
- “Native Libraries” (gpiod, linuxfs, pigpio) as separate blocks.
- “Plugin System” with various plugins (pi4j-plugin-gpiod, pi4j-plugin-linuxfs, etc.).
- “Test Suite (pi4j-test)” and “Distribution/Packaging (pi4j-distribution)” as auxiliary components.
- Detail the “plug-and-play” design through service registry and extension relationships.

- Configuration management (Context, Configuration Builder) that wires these components together upon application startup.
- A highlight of the “build & test” pipeline (Maven build, CI workflows) as supporting infrastructure for the project.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application"
        client["Client Application"]
    end

    subgraph "Core Layer"
        core["Pi4J Core API (pi4j-core)"]
    end

    subgraph "Native Libraries"
        native_gpiod["Native Library – gpiod Integration"]
        native_linuxfs["Native Library – linuxfs Integration"]
        native_pigpio["Native Library – pigpio Integration"]
    end

    subgraph "Plugin Providers"
        plugin_gpiod["Plugin – gpiod Provider"]
        plugin_linuxfs["Plugin – linuxfs Provider"]
        plugin_mock["Plugin – Mock Provider"]
        plugin_pigpio["Plugin – pigpio Provider"]
        plugin_rpi["Plugin – Raspberry Pi Provider"]
    end

    subgraph "Support Modules"
        test["Test Suite (pi4j-test)"]
        distribution["Distribution & Packaging Module (pi4j-distribution)"]
        docs["Documentation & Architecture Diagrams"]
    end

    %% Main Application Flow
    client -->|"uses"| core

    %% Core interacting with Native Libraries
    core -->|"invokes"| native_gpiod
    core -->|"invokes"| native_linuxfs
    core -->|"invokes"| native_pigpio

    %% Core interacting with Plugin Providers
    core -->|"registers"| plugin_gpiod
    core -->|"registers"| plugin_linuxfs
    core -->|"registers"| plugin_mock
    core -->|"registers"| plugin_pigpio
    core -->|"registers"| plugin_rpi

    %% Feedback and Extension Relationships (dashed lines)
    native_gpiod -.->|"feedback"| core
    native_linuxfs -.->|"feedback"| core
    native_pigpio -.->|"feedback"| core

    plugin_gpiod -.->|"extension"| core
    plugin_linuxfs -.->|"extension"| core
    plugin_mock -.->|"extension"| core
    plugin_pigpio -.->|"extension"| core
    plugin_rpi -.->|"extension"| core

    %% Support Modules connecting to the Core API
    test -->|"verifies"| core
    distribution -->|"packages"| core
    docs -->|"documents"| core

    %% Class Definitions for Coloring
    classDef client fill:#ffcdd2,stroke:#b71c1c,stroke-width:2px;
    classDef core fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef native fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef plugin fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
    classDef support fill:#ffe0b2,stroke:#e65100,stroke-width:2px;

    class client client;
    class core core;
    class native_gpiod,native_linuxfs,native_pigpio native;
    class plugin_gpiod,plugin_linuxfs,plugin_mock,plugin_pigpio,plugin_rpi plugin;
    class test,distribution,docs support;

    %% Click Events
    click core "https://github.com/pi4j/pi4j/tree/develop/pi4j-core"
    click native_gpiod "https://github.com/pi4j/pi4j/tree/develop/libraries/pi4j-library-gpiod"
    click native_linuxfs "https://github.com/pi4j/pi4j/tree/develop/libraries/pi4j-library-linuxfs"
    click native_pigpio "https://github.com/pi4j/pi4j/tree/develop/libraries/pi4j-library-pigpio"
    click plugin_gpiod "https://github.com/pi4j/pi4j/tree/develop/plugins/pi4j-plugin-gpiod"
    click plugin_linuxfs "https://github.com/pi4j/pi4j/tree/develop/plugins/pi4j-plugin-linuxfs"
    click plugin_mock "https://github.com/pi4j/pi4j/tree/develop/plugins/pi4j-plugin-mock"
    click plugin_pigpio "https://github.com/pi4j/pi4j/tree/develop/plugins/pi4j-plugin-pigpio"
    click plugin_rpi "https://github.com/pi4j/pi4j/tree/develop/plugins/pi4j-plugin-raspberrypi"
    click test "https://github.com/pi4j/pi4j/tree/develop/pi4j-test"
    click distribution "https://github.com/pi4j/pi4j/tree/develop/pi4j-distribution"
    click docs "https://github.com/pi4j/pi4j/blob/develop/assets/draw.io"
```
