# opendronemap/nodeodm architecture

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

- Interactive diagram: https://gitdiagram.com/opendronemap/nodeodm
- Repository: https://github.com/opendronemap/nodeodm

## Overview

##### Project type and purpose
- NodeODM is a Node.js–based REST API server (“backend”) that orchestrates aerial‐image processing jobs by spawning OpenDroneMap (ODM) engines in containers. It implements the standard NodeODM API used by clients such as WebODM, CloudODM and PyODM.

##### File structure
- Top level:
- index.js – entry point, sets up HTTP server (Express) and routes
- config.js / config-default.json – configuration loader
- Dockerfile(.gpu/.gpu.intel) + apptainer.def – container builds
- public/ – static web assets (CSS/JS/locales) for UI demos
- libs/ – core modules: auth, task & process management, ODM runner, S3 support, logging, utilities
- helpers/ – scripting helpers (Python, batch)
- scripts/ – post‐processing, bundling scripts
- services/ – OS service unit files (systemd)
- processes.json – PM2 process manager config
- contrib/docker-compose.* – multi‐container orchestration examples
- tests/ – mock data and unit/integration tests
- Patterns: modular folder per concern, adapter pattern for auth (NoToken, SimpleToken, IP), storage (local FS vs. S3), plugin‐style task runner, test‐mode stubs.

##### Insights from README
- Describes Docker and Apptainer deployment
- Exposes API docs in docs/index.adoc
- Supports GPU (via CUDA‐enabled base image), Windows bundle, PM2 process management
- “Test mode” simulates ODM calls using tests/ mocks

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Clients
    subgraph "External Clients"
        direction TB
        ClientWebODM["WebODM"]:::client
        ClientPyODM["PyODM"]:::client
        ClientCLI["curl/CLI"]:::client
    end

    %% NodeODM API Server
    subgraph "NodeODM API Server"
        direction TB

        EntryPoint["index.js\n(HTTP/API Layer)"]:::server
        Routers["libs/apps.js\n(Express Routers)"]:::server
        ConfigLoader["config.js\nconfig-default.json"]:::server

        subgraph "Auth Middleware"
            direction TB
            AuthFactory["factory.js"]:::server
            TokenAuthBase["TokenAuthBase.js"]:::server
            SimpleTokenAuth["SimpleTokenAuth.js"]:::server
            NoTokenAuth["NoTokenRequiredAuth.js"]:::server
            TokenIpAuth["TokenIpAuth.js"]:::server
        end

        subgraph "Task Manager"
            direction TB
            TaskManager["TaskManager.js"]:::server
            Task["Task.js"]:::server
            ProgressReceiver["ProgressReceiver.js"]:::server
            TaskNew["taskNew.js"]:::server
        end

        subgraph "ODM Runner"
            direction TB
            OdmRunner["odmRunner.js"]:::server
            ProcessRunner["processRunner.js"]:::server
        end

        subgraph "Storage Adapter"
            direction TB
            S3Adapter["S3.js"]:::storage
            LocalFS["Directories.js"]:::storage
        end

        subgraph "Logging & Utils"
            direction TB
            Logger["logger.js"]:::server
            Utils["utils.js"]:::server
            ZipUtils["ziputils.js"]:::server
            StatusCodes["statusCodes.js"]:::server
        end

    end

    %% Container Execution
    subgraph "Container Execution"
        direction TB
        ODMContainer["ODM Docker/Apptainer"]:::container
    end

    %% Data & Storage
    subgraph "Data & Storage"
        direction TB
        MountedVolume["Local Volume"]:::storage
        S3Bucket["S3 Bucket"]:::storage
    end

    %% Process Manager
    PM2Config["processes.json\n(PM2 Process Manager)"]:::process

    %% Static UI & Demo Assets
    PublicAssets["public/"]:::script

    %% Docker & Apptainer Builds
    subgraph "Container Builds"
        direction TB
        Dockerfile["Dockerfile"]:::script
        DockerGPU["Dockerfile.gpu"]:::script
        DockerGPUIntel["Dockerfile.gpu.intel"]:::script
        ApptainerDef["apptainer.def"]:::script
    end

    %% Helper Scripts
    subgraph "Helper Scripts"
        direction TB
        PythonSerializer["odmOptionsToJson.py"]:::script
        BatchHelper["odm_python.bat"]:::script
        PostProcessScript["postprocess.sh"]:::script
        WinBundle["winbundle.js"]:::script
    end

    %% Service Unit
    NodeODMService["nodeodm.service"]:::script

    %% Documentation & API Docs
    subgraph "Documentation & API Docs"
        direction TB
        IndexAdoc["index.adoc"]:::docs
        SwaggerJSON["swagger.json"]:::docs
        GenerateDocsSh["generateDocs.sh"]:::docs
        GenerateDocsBat["generateDocs.bat"]:::docs
        GenerateSwaggerAPI["generateSwaggerAPI.js"]:::docs
    end

    %% Tests & Mocks
    Tests["tests/"]:::test

    %% Connections
    ClientWebODM -->|POST /tasks| EntryPoint
    ClientPyODM -->|POST /tasks| EntryPoint
    ClientCLI -->|POST /tasks| EntryPoint

    EntryPoint -->|uses| Routers
    EntryPoint -->|loads| ConfigLoader
    EntryPoint -->|supervised by| PM2Config

    Routers -->|calls| AuthFactory
    AuthFactory -->|selects| TokenAuthBase
    AuthFactory -->|selects| SimpleTokenAuth
    AuthFactory -->|selects| NoTokenAuth
    AuthFactory -->|selects| TokenIpAuth

    Routers -->|invokes| TaskManager
    TaskManager -->|manages| Task
    TaskManager -->|receives| ProgressReceiver
    TaskManager -->|creates| TaskNew
    TaskManager -->|spawns| OdmRunner

    OdmRunner -->|uses| ProcessRunner
    OdmRunner -->|executes| ODMContainer
    ProcessRunner -->|reports| ProgressReceiver
    ODMContainer -->|writes to| MountedVolume
    ODMContainer -->|writes to| S3Bucket

    MountedVolume --- LocalFS
    S3Bucket --- S3Adapter

    %% Polling flow
    ClientWebODM -->|GET /tasks/:id| EntryPoint
    ClientPyODM -->|GET /tasks/:id| EntryPoint
    ClientCLI -->|GET /tasks/:id| EntryPoint
    EntryPoint -->|queries| TaskManager

    %% Logging & Utils usage
    EntryPoint -->|logs via| Logger
    TaskManager -->|logs via| Logger
    OdmRunner -->|utils| Utils
    TaskManager -->|utils| ZipUtils
    TaskManager -->|utils| StatusCodes

    %% Additional components
    EntryPoint -->|serves| PublicAssets
    EntryPoint -->|build context| Dockerfile
    EntryPoint -->|build context| DockerGPU
    EntryPoint -->|build context| DockerGPUIntel
    EntryPoint -->|build context| ApptainerDef

    EntryPoint -->|runs| PythonSerializer
    EntryPoint -->|runs| BatchHelper
    EntryPoint -->|runs| PostProcessScript
    EntryPoint -->|runs| WinBundle

    EntryPoint -->|service unit| NodeODMService

    EntryPoint -->|generates| IndexAdoc
    EntryPoint -->|reads| SwaggerJSON
    EntryPoint -->|executes| GenerateDocsSh
    EntryPoint -->|executes| GenerateDocsBat
    EntryPoint -->|executes| GenerateSwaggerAPI

    EntryPoint -->|test mode| Tests

    %% Click Events
    click EntryPoint "https://github.com/opendronemap/nodeodm/blob/master/index.js"
    click ConfigLoader "https://github.com/opendronemap/nodeodm/blob/master/config.js"
    click ConfigLoader "https://github.com/opendronemap/nodeodm/blob/master/config-default.json"
    click Routers "https://github.com/opendronemap/nodeodm/blob/master/libs/apps.js"
    click TokenAuthBase "https://github.com/opendronemap/nodeodm/blob/master/libs/auth/TokenAuthBase.js"
    click SimpleTokenAuth "https://github.com/opendronemap/nodeodm/blob/master/libs/auth/SimpleTokenAuth.js"
    click NoTokenAuth "https://github.com/opendronemap/nodeodm/blob/master/libs/auth/NoTokenRequiredAuth.js"
    click TokenIpAuth "https://github.com/opendronemap/nodeodm/blob/master/libs/auth/TokenIpAuth.js"
    click AuthFactory "https://github.com/opendronemap/nodeodm/blob/master/libs/auth/factory.js"
    click TaskManager "https://github.com/opendronemap/nodeodm/blob/master/libs/TaskManager.js"
    click Task "https://github.com/opendronemap/nodeodm/blob/master/libs/Task.js"
    click ProgressReceiver "https://github.com/opendronemap/nodeodm/blob/master/libs/ProgressReceiver.js"
    click TaskNew "https://github.com/opendronemap/nodeodm/blob/master/libs/taskNew.js"
    click OdmRunner "https://github.com/opendronemap/nodeodm/blob/master/libs/odmRunner.js"
    click ProcessRunner "https://github.com/opendronemap/nodeodm/blob/master/libs/processRunner.js"
    click S3Adapter "https://github.com/opendronemap/nodeodm/blob/master/libs/S3.js"
    click LocalFS "https://github.com/opendronemap/nodeodm/blob/master/libs/Directories.js"
    click Logger "https://github.com/opendronemap/nodeodm/blob/master/libs/logger.js"
    click Utils "https://github.com/opendronemap/nodeodm/blob/master/libs/utils.js"
    click ZipUtils "https://github.com/opendronemap/nodeodm/blob/master/libs/ziputils.js"
    click StatusCodes "https://github.com/opendronemap/nodeodm/blob/master/libs/statusCodes.js"
    click PublicAssets "https://github.com/opendronemap/nodeodm/tree/master/public/"
    click Dockerfile "https://github.com/opendronemap/nodeodm/tree/master/Dockerfile"
    click DockerGPU "https://github.com/opendronemap/nodeodm/blob/master/Dockerfile.gpu"
    click DockerGPUIntel "https://github.com/opendronemap/nodeodm/blob/master/Dockerfile.gpu.intel"
    click ApptainerDef "https://github.com/opendronemap/nodeodm/blob/master/apptainer.def"
    click PM2Config "https://github.com/opendronemap/nodeodm/blob/master/processes.json"
    click PythonSerializer "https://github.com/opendronemap/nodeodm/blob/master/helpers/odmOptionsToJson.py"
    click BatchHelper "https://github.com/opendronemap/nodeodm/blob/master/helpers/odm_python.bat"
    click PostProcessScript "https://github.com/opendronemap/nodeodm/blob/master/scripts/postprocess.sh"
    click WinBundle "https://github.com/opendronemap/nodeodm/blob/master/scripts/winbundle.js"
    click NodeODMService "https://github.com/opendronemap/nodeodm/blob/master/services/nodeodm.service"
    click IndexAdoc "https://github.com/opendronemap/nodeodm/blob/master/docs/index.adoc"
    click SwaggerJSON "https://github.com/opendronemap/nodeodm/blob/master/docs/swagger.json"
    click GenerateDocsSh "https://github.com/opendronemap/nodeodm/blob/master/docs/generateDocs.sh"
    click GenerateDocsBat "https://github.com/opendronemap/nodeodm/blob/master/docs/generateDocs.bat"
    click GenerateSwaggerAPI "https://github.com/opendronemap/nodeodm/blob/master/docs/generateSwaggerAPI.js"
    click Tests "https://github.com/opendronemap/nodeodm/tree/master/tests/"

    %% Styles
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px
    classDef container fill:#98FB98,stroke:#333,stroke-width:1px
    classDef process fill:#FFD580,stroke:#333,stroke-width:1px
    classDef script fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef docs fill:#EEE8AA,stroke:#333,stroke-width:1px
    classDef test fill:#F08080,stroke:#333,stroke-width:1px
```
