# ossimlabs/ossim-ubuntu architecture

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

- Interactive diagram: https://gitdiagram.com/ossimlabs/ossim-ubuntu
- Repository: https://github.com/ossimlabs/ossim-ubuntu

## Overview

##### Project Type and Purpose
- This is not a web app but a container-based build and packaging pipeline for the OSSIM library (a remote sensing/image-processing SDK).
- It orchestrates three main stages:
a. Building a “builder” Docker image with all native dependencies (builder-image).
b. Compiling OSSIM inside that image and producing an installable archive (compile-ossim).
c. Assembling a minimal runtime Docker image containing only the OSSIM runtime bits (runtime).
- Jenkins is used to automate both builder and runtime image builds (jenkins-builder & jenkins-runtime folders). There’s also a “dev” folder for local, manual iteration.

##### High-Level Architecture and Components
A. Source Control (Git)
- Triggers Jenkins pipelines and is cloned by local dev.
B. CI/CD Server (Jenkins)
- Two pipelines (Jenkinsfiles):
- jenkins-builder: builds and tags the builder-image.
- jenkins-runtime: builds the final runtime image from the OSSIM artifact.
C. Docker Engine
- Builds three images:
1. Dependency Builder Image (builder-image/Dockerfile + build-scripts).
2. OSSIM Compiler Stage (compile-ossim/build-scripts invoked inside the builder-image).
3. OSSIM Runtime Image (runtime/Dockerfile + runtime scripts).
D. Artifact Storage
- Docker registry (could be Docker Hub, ECR, GCR) holds images.
- A tarball (output/ossim-dist-minimal-ubuntu.tgz) is produced by the compile-ossim stage and may be stored in an artifact server or passed directly into the runtime build.
E. External Dependencies
- Third-party repos for FFmpeg, HDF5, x264, x265, SZIP, Kakadu, etc., checked out by builder scripts.

##### Relationships and Data Flows
1. Developer or Jenkins Pipeline checks out the Git repo.
2. For builder-image stage:
- build-image/build.sh → Docker build of builder-image → inside container run build-scripts/* → produce ossim-builder-minimal-ubuntu:local.
- On success, image is tagged & pushed to registry (via dev scripts or Jenkins “tag_and_push.sh”).
3. For compile-ossim stage:
- compile-ossim/build.sh -> runs in host or in builder-image container → compiles OSSIM, runs install to /output → packages output tarball.
4. For runtime stage:
- runtime/build-docker.sh → takes the OSSIM tarball as input (via COPY or volume) → builds runtime image → tags and pushes.
5. Developers can also use the dev/ scripts for local iteration, using Docker directly.

##### Architectural Patterns & Principles
- Separation of Concerns:
- Builder image (heavyweight, compilers & dev dependencies) vs. Runtime image (lightweight, only runtime).
- Immutable Infrastructure: all builds happen in Docker; the result is a versioned image or artifact.
- Staged Pipeline: three sequential stages reflect a compiler/packager pipeline (fetch → build deps → compile → package → runtime).
- Scripted Automation: build-scripts, checkout-scripts, and dev/ scripts encapsulate all build logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Source Control"
        Git["Git Repo"]:::external
    end

    subgraph "CI/CD Server"
        JenkinsBuilder["Jenkins Builder Pipeline"]:::pipeline
        JenkinsRuntime["Jenkins Runtime Pipeline"]:::pipeline
    end

    subgraph "Local Development"
        DevDockerfile["dev/Dockerfile"]:::script
        DevScripts["dev/*.sh"]:::script
    end

    subgraph "Docker Engine"
        subgraph "Builder Stage"
            BuilderBuildSh["builder-image/build.sh"]:::script
            BuilderCheckoutScripts["builder-image/checkout-scripts/"]:::script
            BuilderBuildScripts["builder-image/build-scripts/"]:::script
            BuilderImageDockerfile["builder-image/Dockerfile"]:::script
        end
        subgraph "Compile Stage"
            CompileCheckout["compile-ossim/checkout-ossim.sh"]:::script
            CompileBuildSh["compile-ossim/build.sh"]:::script
            CompileBuildScripts["compile-ossim/build-scripts/"]:::script
            OssimTarball["ossim-dist-minimal-ubuntu.tgz"]:::artifact
        end
        subgraph "Runtime Stage"
            RuntimeBuildDocker["runtime/build-docker.sh"]:::script
            RuntimeDockerfile["runtime/Dockerfile"]:::script
            RuntimeRunDocker["runtime/run-docker.sh"]:::script
            RuntimeRunJava["runtime/run-java.sh"]:::script
            RuntimeDataInfo["runtime/dataInfo.sh"]:::script
        end
    end

    subgraph "Artifact Storage"
        DockerRegistry["Docker Registry"]:::artifact
        ArtifactServer["Artifact Server"]:::artifact
    end

    subgraph "External Dependencies"
        ExternalRepos["Third-party Repos"]:::external
    end

    %% Connections
    Git -->|"trigger"| JenkinsBuilder
    Git -->|"trigger"| JenkinsRuntime
    Git -->|"clone"| DevDockerfile
    Git -->|"clone"| DevScripts

    JenkinsBuilder -->|"runs build.sh"| BuilderBuildSh
    BuilderBuildSh -->|"checkout deps"| BuilderCheckoutScripts
    BuilderBuildSh -->|"run build-scripts"| BuilderBuildScripts
    BuilderBuildSh -->|"docker build builder-image"| BuilderImageDockerfile
    BuilderBuildSh -->|"push builder-image"| DockerRegistry

    ExternalRepos --> BuilderBuildSh

    BuilderImageDockerfile -->|"docker run compile"| CompileBuildSh
    CompileBuildSh -->|"checkout ossim"| CompileCheckout
    CompileBuildSh -->|"run build-scripts"| CompileBuildScripts
    CompileBuildSh -->|"produce tarball"| OssimTarball

    ExternalRepos --> CompileBuildSh

    OssimTarball -->|"input to"| RuntimeBuildDocker
    JenkinsRuntime -->|"runs build-docker.sh"| RuntimeBuildDocker
    RuntimeBuildDocker -->|"docker build runtime"| RuntimeDockerfile
    RuntimeBuildDocker -->|"push runtime-image"| DockerRegistry

    DevScripts -->|"local build"| BuilderBuildSh
    DevScripts -->|"local compile"| CompileBuildSh
    DevScripts -->|"local runtime"| RuntimeBuildDocker

    %% Click Events
    click BuilderBuildSh "https://github.com/ossimlabs/ossim-ubuntu/blob/dev/builder-image/build.sh"
    click BuilderCheckoutScripts "https://github.com/ossimlabs/ossim-ubuntu/tree/dev/builder-image/checkout-scripts/"
    click BuilderBuildScripts "https://github.com/ossimlabs/ossim-ubuntu/tree/dev/builder-image/build-scripts/"
    click BuilderImageDockerfile "https://github.com/ossimlabs/ossim-ubuntu/tree/dev/builder-image/Dockerfile"
    click CompileCheckout "https://github.com/ossimlabs/ossim-ubuntu/blob/dev/compile-ossim/checkout-ossim.sh"
    click CompileBuildSh "https://github.com/ossimlabs/ossim-ubuntu/blob/dev/compile-ossim/build.sh"
    click CompileBuildScripts "https://github.com/ossimlabs/ossim-ubuntu/tree/dev/compile-ossim/build-scripts/"
    click RuntimeBuildDocker "https://github.com/ossimlabs/ossim-ubuntu/blob/dev/runtime/build-docker.sh"
    click RuntimeDockerfile "https://github.com/ossimlabs/ossim-ubuntu/tree/dev/runtime/Dockerfile"
    click RuntimeRunDocker "https://github.com/ossimlabs/ossim-ubuntu/blob/dev/runtime/run-docker.sh"
    click RuntimeRunJava "https://github.com/ossimlabs/ossim-ubuntu/blob/dev/runtime/run-java.sh"
    click RuntimeDataInfo "https://github.com/ossimlabs/ossim-ubuntu/blob/dev/runtime/dataInfo.sh"
    click JenkinsBuilder "https://github.com/ossimlabs/ossim-ubuntu/tree/dev/jenkins-builder/Jenkinsfile"
    click JenkinsRuntime "https://github.com/ossimlabs/ossim-ubuntu/tree/dev/jenkins-runtime/Jenkinsfile"
    click DevDockerfile "https://github.com/ossimlabs/ossim-ubuntu/tree/dev/dev/Dockerfile"
    click DevScripts "https://github.com/ossimlabs/ossim-ubuntu/blob/dev/dev/*.sh"

    %% Styling
    classDef external fill:#dddddd,stroke:#666,stroke-width:1px
    classDef pipeline fill:#ccf,stroke:#339,stroke-width:2px
    classDef script fill:#cfc,stroke:#272,stroke-width:1px
    classDef artifact fill:#fcf,stroke:#933,stroke-width:2px
    class Git,JenkinsBuilder,JenkinsRuntime external
    class BuilderBuildSh,BuilderCheckoutScripts,BuilderBuildScripts,BuilderImageDockerfile,CompileCheckout,CompileBuildSh,CompileBuildScripts,RuntimeBuildDocker,RuntimeDockerfile,RuntimeRunDocker,RuntimeRunJava,RuntimeDataInfo,DevDockerfile,DevScripts script
    class OssimTarball,DockerRegistry,ArtifactServer artifact
    class ExternalRepos external
```
