# iseki0/executables architecture

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

- Interactive diagram: https://gitdiagram.com/iseki0/executables
- Repository: https://github.com/iseki0/executables

## Overview

##### Main Components
- Library Core:
- Common Module: Contains shared code for file access, data abstraction, exception definitions, common utilities, and format detection (this is visible in packages like space.iseki.executables.common and share).
- Format-Specific Module(s):
- PE Parser: Contains classes and functions to parse COFF headers, optional headers, version information, and resource data.
- ELF Parser: Contains the logic to parse ELF headers, section headers, symbol tables, etc.
- Macho Parser: Contains the implementation for reading Macho file information.
- Platform-Specific/Binary Adaptors:
- Separate targets for JVM, mingwX64, Native, and nonJvm components (visible in directories: src/jvmMain, src/mingwX64Main, src/nativeFileSupportedMain, etc.). These adapt the core library functionality for different runtime environments or file-access APIs.
- Build & Dev Infrastructure:
- Gradle scripts and buildSrc modules (build.gradle.kts files, settings.gradle.kts) that manage building, testing, and publishing. Also shown is GitHub Actions workflows for continuous integration.
- Tests:
- Organized under commonTest, jvmTest, mingwX64Test, etc. to validate each module and platform-specific behavior.

##### Relationships and Data Flow
- External Client/Application: An external user or application calls the library’s public API (for example, using functions like PEFile.open() or ELFFile.open()).
- File Format Detection: The public API likely first invokes utilities in the “common” module to detect the file format (using FileFormat.detect()). Based on the detected format, it routes the processing to the appropriate parser.
- Format-Specific Processing: After detection, control passes to one of the format-specific components (PE, ELF, or Macho parser). These components further call into submodules that handle reading headers, sections, symbol tables, and other details.
- Platform Abstraction Layer: Depending on the running target (JVM, native, etc.), platform-specific code (in directories like jvmMain, mingwX64Main, etc.) ensures proper file I/O and data access.
- Exception and Logging: Exception handling components in the common module manage errors during parsing. This error handling flows upward to the clients.

##### Architectural Patterns
- Separation of Concerns: Clear modularity between shared logic (common) and format-specific implementations.
- Multiplatform Abstraction: Using Kotlin Multiplatform to factor out common code while providing specific implementations for different targets.
- API Facade: The public APIs (e.g., PEFile, ELFFile, etc.) serve as facades, encapsulating lower-level parsing logic.

##### Technologies and Tools
- Kotlin Multiplatform and Gradle (as build system)
- GitHub Actions (CI workflows; see .github/workflows)
- Testing Frameworks as seen in the test directories
- Serialization (Kotlinx.serialization used in the samples)
- Maven Central (for dependency distribution)

##### Elements
- External Client / Application
- API Facade (public functions like PEFile.open, ELFFile.open, etc.)
- File Format Detector (common utilities)
- Format Parsers: PE Parser, ELF Parser, Macho Parser
- Common Utilities & Exception Handling Module
- Platform-Specific Adapters (JVM adapter, Native adapter, etc.)
- Build & CI Infrastructure (optional, to illustrate overall project maintenance)
- From the external client to the API Facade
- From the API Facade to the File Format Detector, and then branching out to the appropriate format parser
- Core library modules versus platform-specific modules
- Public API layers versus internal logic
- Annotations where necessary that call out important architectural patterns like “Separation of Concerns” and “Platform Abstraction.”

##### Final Advice
- Every component is clearly labeled, grouping submodules appropriately (e.g., grouping the many “files/src/commonMain/kotlin/space/iseki/executables/…” into a single “Executables Core” module with internally labeled subcomponents like “ELF”, “PE”, “Macho”).
- Small notations regarding tools (like Gradle) and CI (like GitHub Action).

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interaction
    EX("External Client/Application"):::external

    subgraph "Public API Facade"
        API1("Facade Endpoint 1"):::api
        API2("Facade Endpoint 2"):::api
    end

    %% Library Core: Common and Parsing Modules
    subgraph "Library Core"
        CM("Common Code & Utilities"):::common
        SU("Shared Utilities"):::common
        FD("File Format Detector"):::common
        PE("PE Parser"):::parser
        ELF("ELF Parser"):::parser
        MACHO("Macho Parser"):::parser
    end

    %% Platform-Specific/Binary Adapters
    subgraph "Platform Adapters"
        JVM("JVM Adapter"):::platform
        MINGW("mingwX64 Adapter"):::platform
        NATIVE("Native/NonJvm Adapter"):::platform
    end

    %% Build & Dev Infrastructure
    subgraph "Build & CI Infrastructure"
        GRAD("Gradle Scripts"):::infra
        BS("buildSrc Module"):::infra
        GHA("GitHub Actions"):::infra
    end

    %% Flow Connections
    EX -->|"calls"| API1
    EX -->|"calls"| API2

    API1 -->|"calls"| FD
    API2 -->|"calls"| FD

    FD -->|"if_PE"| PE
    FD -->|"if_ELF"| ELF
    FD -->|"if_Macho"| MACHO

    PE -->|"parses_headers"| CM
    ELF -->|"parses_headers"| CM
    MACHO -->|"parses_headers"| CM

    CM -->|"aggregates_result"| API1

    CM -->|"I/O_call"| JVM
    CM -->|"I/O_call"| MINGW
    CM -->|"I/O_call"| NATIVE

    JVM -->|"I/O_response"| CM
    MINGW -->|"I/O_response"| CM
    NATIVE -->|"I/O_response"| CM

    GRAD ---|"builds_and_tests"| CM
    BS ---|"builds_and_tests"| CM
    GHA ---|"CI_workflow"| CM

    %% Click Events for Component Mapping
    click CM "https://github.com/iseki0/executables/tree/master/files/src/commonMain/kotlin/space/iseki/executables/common"
    click SU "https://github.com/iseki0/executables/tree/master/files/src/commonMain/kotlin/space/iseki/executables/share"
    click PE "https://github.com/iseki0/executables/tree/master/files/src/commonMain/kotlin/space/iseki/executables/pe"
    click ELF "https://github.com/iseki0/executables/tree/master/files/src/commonMain/kotlin/space/iseki/executables/elf"
    click MACHO "https://github.com/iseki0/executables/tree/master/files/src/commonMain/kotlin/space/iseki/executables/macho"
    click JVM "https://github.com/iseki0/executables/tree/master/files/src/jvmMain/kotlin/space/iseki/executables/common"
    click MINGW "https://github.com/iseki0/executables/tree/master/files/src/mingwX64Main/kotlin/space/iseki/executables/common"
    click NATIVE "https://github.com/iseki0/executables/tree/master/files/src/nativeFileSupportedMain/kotlin/space/iseki/executables/common"
    click API1 "https://github.com/iseki0/executables/blob/master/api/executables.api"
    click API2 "https://github.com/iseki0/executables/blob/master/files/api/files.api"
    click GRAD "https://github.com/iseki0/executables/blob/master/build.gradle.kts"
    click BS "https://github.com/iseki0/executables/tree/master/buildSrc/"
    click GHA "https://github.com/iseki0/executables/tree/master/.github/workflows"

    %% Styles
    classDef external fill:#ffecb3,stroke:#ff9800,stroke-width:2px;
    classDef api fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef common fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef parser fill:#fff9c4,stroke:#f57f17,stroke-width:2px;
    classDef platform fill:#b3e5fc,stroke:#01579b,stroke-width:2px;
    classDef infra fill:#e0e0e0,stroke:#424242,stroke-width:2px;
```
