oshi/oshi

<explanation>

1. Project Type and Purpose

- OSHI is an open‑source Java library (multi‑module Maven project) that provides a cross‑platform API to retrieve operating system and hardware information using JNA (Java Native Access). It exposes a simple facade (SystemInfo) that applications can call to access detailed OS and hardware metrics without requiring external native libraries.

2. High‑Level Architecture Analysis

- Top‑level modules:

• oshi-core-java11 / oshi-core: Core library modules providing the public API, abstraction layers, platform drivers, utilities, and tests.

• oshi-demo: A proof‑of‑concept application suite (Swing GUI, HTTP server, JMX agent) that depends on oshi-core.

• oshi-dist: Assembly/distribution descriptor.

• config / .github / CI files: Build, style, and CI configuration.

• src/site: Documentation, guides, and markdown pages.

3. Core Components to Model

a. Public API Facade

– SystemInfo (entry point)

– HardwareAbstractionLayer, OperatingSystem interfaces

b. Abstraction Interfaces (common package)

– AbstractCentralProcessor, AbstractComputerSystem, AbstractGlobalMemory, etc.

– AbstractOperatingSystem, AbstractOSProcess, AbstractOSFileStore, etc.

c. Platform‑Specific Implementations

– oshi.hardware.platform.* for Linux, macOS, Windows, UNIX variants

– oshi.software.os.* for each OS

d. JNA Bindings

– oshi.jna.platform.*: Low‑level JNA mapping to native OS libraries (libc, Kernel32, Perfmon, WMI, sysctl, etc.)

e. Utilities

– oshi.util: Shared utilities (command execution, parsing, config, memoization)

f. Demo Layer

– Swing GUI components (oshi-demo/src/main/java/oshi/demo/gui)

– HTTP server (OshiHTTPServer)

– JMX agent and strategies (oshi-demo/jmx)

4. Relationships and Data Flow

- Customer code (e.g., Swing GUI, HTTP server, JMX agent, or any third‑party) → invokes SystemInfo.getHardware() or .getOperatingSystem()

- SystemInfo → delegates to HardwareAbstractionLayer and OperatingSystem interfaces

- Abstract interfaces → select correct platform implementation at runtime based on PlatformEnum

- Platform implementation → calls underlying JNA binding classes to execute native calls / read /proc / registry / WMI / sysctl → returns raw data

- Implementation layer → maps raw data into Java model classes (CentralProcessor, GlobalMemory, OSProcess, FileStore, etc.)

- Utilities support caching, parsing, formatting, and configuration reads from oshi.properties

5. Architectural Patterns & Principles

- Abstraction & Separation of Concerns: clear separation between common interfaces, platform‑specific implementations, and JNA bindings

- Factory / Strategy Pattern: dynamic resolution of the correct platform implementation using PlatformEnum and service lookup

- Layered Architecture:

1) Public API layer

2) Abstraction layer (interfaces + abstract classes)

3) Platform drivers

4) JNA/native call layer

- Modularization: Multi‑module Maven setup to isolate Java11 JPMS support and demo code

- Extensibility: Adding support for a new OS or sensor only requires adding a new platform package implementing the existing interfaces

6. Diagramming Guidelines Tailored to OSHI

- Use a large rectangle to represent the “oshi-core” module. Inside it, draw horizontally stacked layers:

1) API Facade (SystemInfo, GlobalConfig)

2) Abstraction Interfaces & Abstract Classes (common)

3) Platform Drivers (one sub‑block for each OS: Windows, Linux, macOS, AIX, FreeBSD, OpenBSD, Solaris)

4) JNA Bindings (sub‑blocks for platform/windows, platform/linux, platform/mac, etc.)

5) Utilities (oshi.util)

- Depict external elements:

• Native OS / kernel (Windows API, Linux /proc & sysfs, macOS IOKit, UNIX sysctl)

• Optional dependencies: jLibreHardwareMonitor (for Windows sensors)

- Draw arrows:

• From API Facade → Abstraction Interfaces

• From Interfaces → Platform Drivers

• From Drivers → JNA Bindings

• From JNA Bindings → External Native OS

- Show the oshi-demo module in parallel, depending on oshi-core:

• Swing GUI, HTTP server, JMX agent (each as a sub‑component)

- Optionally illustrate the Maven reactor structure: core modules, demo module, distribution assembly

7. Diagram Elements

- Labels: clearly name each component (e.g., SystemInfo, HardwareAbstractionLayer, LinuxHardwareAbstractionLayer, Kernel32 JNA binding)

- Arrows: directional, annotated with key method calls or data (e.g., “getProcessor() → LinuxCentralProcessor → Sysfs.read()”)

- Colors / Shapes:

• Blue rectangles for modules/packages

• Green for interfaces/abstract classes

• Orange for platform‑specific implementations

• Purple for JNA/native binding classes

• Gray cylinder for external Native OS layer

8. Level of Detail

- Don’t try to draw every single class. Group classes by package or responsibility (e.g., all Linux drivers in one box).

- Emphasize extensibility points: where a new OS would plug in.

- Highlight configuration path: oshi.properties → GlobalConfig → influences driver behavior.

9. Final Advice

- Capture all essential layers: API → abstraction → platform → native

- Show dependencies between modules (oshi-core, oshi-demo, oshi-dist)

- Use clear, consistent shapes and colors for quick comprehension

- Annotate key flows (e.g., how SystemInfo picks and invokes a platform driver via JNA)

- Keep it detailed enough to show “where to add a new OS” and “how the native call flows,” but abstract away per‑class minutiae.

- As an open‑source tool, focus on the core library structure and the extensibility interfaces rather than the demo UI details.

Using these guidelines, you’ll produce a system design diagram that accurately conveys OSHI’s layered architecture, its extensibility, and its runtime flow from Java API down to native OS calls.