# opnsense/tools architecture

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

- Interactive diagram: https://gitdiagram.com/opnsense/tools
- Repository: https://github.com/opnsense/tools

## Overview

##### Main Components

a) Repository Layer:
- Core Repository (core.git)
- Ports Repository (ports.git)
- Source Repository (src.git)
- Plugins Repository (plugins.git)
- Tools Repository (current project)

b) Build System Components:
- Configuration Management (/config directory)
- Build Scripts (/build directory)
- Composite Scripts (/composite directory)
- Device-Specific Configurations (/device directory)
- Utility Scripts (/scripts directory)

c) Output Components:
- Sets Directory (for built components)
- Images Directory (for final images)
- Logs Directory (for build logs)

##### Component Relationships

**[Input Layer]**

- v
**[Build System Core]**

**[Build Steps]  [Configurations]  [Device Specs]**

- v
**[Output Layer]**

##### Specific Implementation Details

a) Build Process Flow:
- Main build steps: base → kernel → ports → plugins → core
- Parallel paths for different image types (dvd, serial, vga, vm)
- Signing and verification processes

b) Configuration Flow:
- How device-specific configurations modify the build process
- Relationship between build.conf and local overrides

##### Key Elements to Highlight

- Cross-building capabilities for different architectures
- Package management and caching system
- Set management (base, kernel, packages, etc.)
- Image generation paths
- Verification and signing processes

##### Notes for Implementation

- Keep the main flow clear and centered
- Related components together
- Use clear labels for all components
- Version information handling
- Both standard and custom build paths

- Hierarchical layouts
- Text annotations
- Grouping of related components

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef repo fill:#b3d1ff,stroke:#4d88ff
    classDef build fill:#90EE90,stroke:#228B22
    classDef config fill:#FFB366,stroke:#FF8000
    classDef output fill:#DDA0DD,stroke:#9370DB
    classDef device fill:#FFD700,stroke:#DAA520

    %% Repository Layer
    subgraph Repositories
        CoreRepo["Core Repository"]:::repo
        PortsRepo["Ports Repository"]:::repo
        SrcRepo["Source Repository"]:::repo
        PluginsRepo["Plugins Repository"]:::repo
        ToolsRepo["Tools Repository"]:::repo
    end

    %% Build System Core
    subgraph BuildSystem
        CommonFuncs["Common Functions"]:::build
        BuildInfo["Build Information"]:::build
        CleanBuild["Clean Build"]:::build
        TestFuncs["Test Functions"]:::build
    end
    click CommonFuncs "https://github.com/opnsense/tools/blob/master//build/common.sh"
    click BuildInfo "https://github.com/opnsense/tools/blob/master//build/info.sh"
    click CleanBuild "https://github.com/opnsense/tools/blob/master//build/clean.sh"
    click TestFuncs "https://github.com/opnsense/tools/blob/master//build/test.sh"

    %% Configuration Management
    subgraph Configurations
        BuildConf["Build Configuration"]:::config
        PortsConf["Ports Configuration"]:::config
        PluginsConf["Plugins Configuration"]:::config
    end
    click BuildConf "https://github.com/opnsense/tools/blob/master//config/24.7/build.conf"
    click PortsConf "https://github.com/opnsense/tools/blob/master//config/24.7/ports.conf"
    click PluginsConf "https://github.com/opnsense/tools/blob/master//config/24.7/plugins.conf"

    %% Build Steps
    subgraph BuildSteps
        BaseBuild["Base Build"]:::build
        KernelBuild["Kernel Build"]:::build
        PortsBuild["Ports Build"]:::build
        PluginsBuild["Plugins Build"]:::build
        CoreBuild["Core Build"]:::build
    end
    click BaseBuild "https://github.com/opnsense/tools/blob/master//build/base.sh"
    click KernelBuild "https://github.com/opnsense/tools/blob/master//build/kernel.sh"
    click PortsBuild "https://github.com/opnsense/tools/blob/master//build/ports.sh"
    click PluginsBuild "https://github.com/opnsense/tools/blob/master//build/plugins.sh"
    click CoreBuild "https://github.com/opnsense/tools/blob/master//build/core.sh"

    %% Device Configurations
    subgraph DeviceConfigs
        ARM["ARM Devices"]:::device
        RPI["Raspberry Pi"]:::device
        OtherDevices["Other Devices"]:::device
    end
    click ARM "https://github.com/opnsense/tools/blob/master//device/ARM64.conf"
    click RPI "https://github.com/opnsense/tools/blob/master//device/RPI.conf"
    click OtherDevices "https://github.com/opnsense/tools/blob/master//device/CLEARFOG.conf"

    %% Build Types
    subgraph BuildTypes
        CustomBuild["Custom Builds"]:::build
        FactoryBuild["Factory Builds"]:::build
        HotfixBuild["Hotfix Builds"]:::build
        NightlyBuild["Nightly Builds"]:::build
    end
    click CustomBuild "https://github.com/opnsense/tools/blob/master//composite/custom.sh"
    click FactoryBuild "https://github.com/opnsense/tools/blob/master//composite/factory.sh"
    click HotfixBuild "https://github.com/opnsense/tools/blob/master//composite/hotfix.sh"
    click NightlyBuild "https://github.com/opnsense/tools/blob/master//composite/nightly.sh"

    %% Image Generation
    subgraph ImageGen
        DVDImage["DVD Image"]:::output
        SerialConsole["Serial Console"]:::output
        VGAConsole["VGA Console"]:::output
        VM["Virtual Machine"]:::output
    end
    click DVDImage "https://github.com/opnsense/tools/blob/master//build/dvd.sh"
    click SerialConsole "https://github.com/opnsense/tools/blob/master//build/serial.sh"
    click VGAConsole "https://github.com/opnsense/tools/blob/master//build/vga.sh"
    click VM "https://github.com/opnsense/tools/blob/master//build/vm.sh"

    %% Security
    subgraph Security
        PkgSign["Package Signing"]:::build
        Fingerprint["Fingerprinting"]:::build
        Verify["Verification"]:::build
        Sign["Signing"]:::build
    end
    click PkgSign "https://github.com/opnsense/tools/blob/master//scripts/pkg_sign.sh"
    click Fingerprint "https://github.com/opnsense/tools/blob/master//scripts/pkg_fingerprint.sh"
    click Verify "https://github.com/opnsense/tools/blob/master//build/verify.sh"
    click Sign "https://github.com/opnsense/tools/blob/master//build/sign.sh"

    %% Relationships
    Repositories --> BuildSystem
    BuildSystem --> BuildSteps
    Configurations --> BuildSteps
    DeviceConfigs --> BuildSteps
    BuildSteps --> BuildTypes
    BuildTypes --> ImageGen
    BuildTypes --> Security
    Security --> ImageGen

    %% Legend
    subgraph Legend
        L1["Repository Components"]:::repo
        L2["Build Components"]:::build
        L3["Configuration Components"]:::config
        L4["Output Components"]:::output
        L5["Device Components"]:::device
    end
```
