# molaorg/mola architecture

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

- Interactive diagram: https://gitdiagram.com/molaorg/mola
- Repository: https://github.com/molaorg/mola

## Overview

##### Project Type and Purpose
- This is an open-source, modular C++ framework for LiDAR odometry, mapping, and localization (MOLA).

##### High-Level Architecture Overview
A. Entry Points & Orchestration
- CLI “mola_launcher” (loads and wires modules at runtime)
- ROS 2 node bridge (“mola_bridge_ros2”)
B. Core Interfaces & Kernel
- Kernel core library (“mola_kernel”): defines interfaces (DatasetSource, FrontEndBase, BackEndBase, MapServer, VizInterface, FilterBase, etc.) and core data structures (Entity, Factor, WorldModel).
C. Data Sources
- mola_input_* packages (Euroc, KITTI, Rawlog, ROSBag2, Video, Mulran, ParisLuco)
- kitti_metrics_eval (dataset evaluation app)
D. Processing Modules (Plugins)
- Front-end algorithms: lidar odometry, ICP, sensor fusion (“mola_lo_apps”, “mp2p_icp”)
- Back-end optimizers: graph optimization using GTSAM, factor implementations (FactorStereoProjectionPose, SmartFactorIMU, etc.)
- Relocalization modules (“mola_relocalization”)
- Representations (“mola_metric_maps”)
- Pose lists (“mola_pose_list”)
E. Visualization & Output
- mola_viz (local, CLI-based visualization)
- ROS 2 topics & services (messages defined in mola_msgs)
- CLI tools (mola-traj-tools, mola-sm-cli, etc.)
F. Documentation & Devops
- docs/ (Sphinx + Doxygen pipeline)
- .github workflows (build, format checks)
- scripts/ (code formatting, status page generator)

##### Component Relationships & Data Flow
- Data flows from Data Source modules → Core interfaces → Processing modules → Map server / back-end → Visualizers / ROS 2 topics → end user.
- ROS 2 bridge subscribes and publishes on ROS 2 topics to integrate MOLA pipelines into wider ROS 2 graph.

##### Architectural Patterns & Design Principles
- Plugin architecture: modules discoverable at runtime through CMake-registered factories.
- Dependency inversion: higher-level modules depend on abstract interfaces in mola_kernel, not on concrete implementations.
- Separation of concerns:
- Data acquisition (mola_input_*)
- Front-end processing (feature extraction, odometry estimation)
- Back-end optimization (graph solvers, factors)
- Management (mola_metric_maps)
- Visualization and messaging (mola_viz, mola_msgs, mola_bridge_ros2)
- ROS 2 integration: pure C++ modules can be used standalone or as nodes in ROS 2.

##### Detailed Elements to Capture
- mola_launcher as the central orchestrator (shared-lib loader)
- mola_kernel’s interface definitions → implementations in each module
- mola_input_* feeding raw data (point clouds, IMU, images)
- Front-end pipeline modules converting raw data to state estimates
- Back-end modules refining trajectory via optimization (factor graphs)
- Server storing and serving metric maps (grid, voxel, NDT)
- Relocalization module hooking into the back-end for global alignment
- mola_viz and ROS 2 bridge exposing runtime data for visualization
- Message definitions (services and topics) in mola_msgs
- Build system (CMakeLists, colcon_defaults.yaml) and CI pipelines

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry & Orchestration
    subgraph "Entry & Orchestration"
        Launcher["mola_launcher"]:::orch
        BridgeNode["mola_bridge_ros2"]:::bridge
    end

    %% Core Interfaces & Kernel
    subgraph "Core Interfaces & Kernel"
        Kernel["mola_kernel"]:::kernel
    end

    %% Data Sources
    subgraph "Data Acquisition" 
        InputEuroc["mola_input_euroc_dataset"]:::data
        InputKITTI360["mola_input_kitti360_dataset"]:::data
        InputKITTI["mola_input_kitti_dataset"]:::data
        InputMulran["mola_input_mulran_dataset"]:::data
        InputParis["mola_input_paris_luco_dataset"]:::data
        InputRawlog["mola_input_rawlog"]:::data
        InputRosbag2["mola_input_rosbag2"]:::data
        InputVideo["mola_input_video"]:::data
        KittiEval["kitti_metrics_eval"]:::data
    end

    %% Processing Modules
    subgraph "Processing Modules"
        Frontend["Front-end Plugins"]:::proc
        Backend["Back-end Plugins"]:::proc
        Reloc["mola_relocalization"]:::proc
        PoseList["mola_pose_list"]:::proc
    end

    %% Map Storage
    subgraph "Map & Storage"
        MapRepr["mola_metric_maps"]:::storage
    end

    %% Visualization & Output
    subgraph "Visualization & Output"
        Viz["mola_viz"]:::viz
        BridgeTopics["ROS 2 Topics & Services"]:::viz
        Msgs["mola_msgs"]:::viz
        TrajTools["mola_traj_tools"]:::viz
    end

    %% DevOps & Documentation
    subgraph "DevOps & Documentation"
        Docs["docs"]:::docs
        CI[".github/workflows"]:::docs
        Scripts["scripts"]:::docs
        YAML["colcon_defaults.yaml"]:::docs
        CMake["CMakeLists.txt"]:::docs
    end

    %% Data & Implementation Relationships
    InputEuroc -- "implements DatasetSource" --> Kernel
    InputKITTI360 -- "implements DatasetSource" --> Kernel
    InputKITTI -- "implements DatasetSource" --> Kernel
    InputMulran -- "implements DatasetSource" --> Kernel
    InputParis -- "implements DatasetSource" --> Kernel
    InputRawlog -- "implements DatasetSource" --> Kernel
    InputRosbag2 -- "implements DatasetSource" --> Kernel
    InputVideo -- "implements DatasetSource" --> Kernel
    KittiEval -- "uses DatasetSource" --> Kernel

    Kernel -->|"defines interfaces"| Frontend
    Kernel -->|"defines interfaces"| Backend
    Kernel -->|"defines interfaces"| Reloc
    Kernel -->|"defines interfaces"| PoseList

    Frontend -->|"raw→state estimates"| Backend
    Backend -->|"refines trajectory"| MapRepr
    Reloc -- "implements Relocalization" --> Backend
    PoseList -- "exports poses" --> TrajTools

    MapRepr -->|"serves maps"| Viz
    MapRepr -->|"serves maps"| BridgeTopics

    BridgeTopics -->|"pub/sub"| BridgeNode
    Msgs -- "message definitions" --> BridgeTopics

    BridgeNode -->|"invokes pipeline"| Kernel

    %% Launcher Orchestration
    Launcher -.->|"loads plugins"| InputEuroc
    Launcher -.->|"loads plugins"| InputKITTI360
    Launcher -.->|"loads plugins"| InputKITTI
    Launcher -.->|"loads plugins"| InputMulran
    Launcher -.->|"loads plugins"| InputParis
    Launcher -.->|"loads plugins"| InputRawlog
    Launcher -.->|"loads plugins"| InputRosbag2
    Launcher -.->|"loads plugins"| InputVideo
    Launcher -.->|"loads plugins"| KittiEval
    Launcher -.->|"loads plugins"| Frontend
    Launcher -.->|"loads plugins"| Backend
    Launcher -.->|"loads plugins"| Reloc
    Launcher -.->|"loads plugins"| MapRepr
    Launcher -.->|"loads plugins"| PoseList
    Launcher -.->|"loads plugins"| Viz
    Launcher -.->|"loads plugins"| TrajTools

    %% DevOps connections
    YAML -.->|"build defaults"| Launcher
    CMake -.->|"build configs"| Kernel
    CI -.->|"CI pipelines"| CMake
    Scripts -.->|"dev scripts"| CI
    Docs -.->|"generate docs"| Kernel

    %% Click Events
    click Launcher "https://github.com/molaorg/mola/tree/develop/mola_launcher"
    click BridgeNode "https://github.com/molaorg/mola/tree/develop/mola_bridge_ros2"
    click Kernel "https://github.com/molaorg/mola/tree/develop/mola_kernel"
    click InputEuroc "https://github.com/molaorg/mola/tree/develop/mola_input_euroc_dataset"
    click InputKITTI360 "https://github.com/molaorg/mola/tree/develop/mola_input_kitti360_dataset"
    click InputKITTI "https://github.com/molaorg/mola/tree/develop/mola_input_kitti_dataset"
    click InputMulran "https://github.com/molaorg/mola/tree/develop/mola_input_mulran_dataset"
    click InputParis "https://github.com/molaorg/mola/tree/develop/mola_input_paris_luco_dataset"
    click InputRawlog "https://github.com/molaorg/mola/tree/develop/mola_input_rawlog"
    click InputRosbag2 "https://github.com/molaorg/mola/tree/develop/mola_input_rosbag2"
    click InputVideo "https://github.com/molaorg/mola/tree/develop/mola_input_video"
    click KittiEval "https://github.com/molaorg/mola/tree/develop/kitti_metrics_eval"
    click Reloc "https://github.com/molaorg/mola/tree/develop/mola_relocalization"
    click MapRepr "https://github.com/molaorg/mola/tree/develop/mola_metric_maps"
    click PoseList "https://github.com/molaorg/mola/tree/develop/mola_pose_list"
    click Viz "https://github.com/molaorg/mola/tree/develop/mola_viz"
    click Msgs "https://github.com/molaorg/mola/tree/develop/mola_msgs"
    click TrajTools "https://github.com/molaorg/mola/tree/develop/mola_traj_tools"
    click Docs "https://github.com/molaorg/mola/tree/develop/docs"
    click CI "https://github.com/molaorg/mola/tree/develop/.github/workflows"
    click Scripts "https://github.com/molaorg/mola/tree/develop/scripts"
    click YAML "https://github.com/molaorg/mola/blob/develop/colcon_defaults.yaml"
    click CMake "https://github.com/molaorg/mola/blob/develop/CMakeLists.txt"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef kernel fill:#C8E6C9,stroke:#43A047,color:#1B5E20;
    classDef proc fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef storage fill:#D1C4E9,stroke:#8E24AA,color:#4A148C;
    classDef viz fill:#FFF9C4,stroke:#FDD835,color:#F57F17;
    classDef docs fill:#CFD8DC,stroke:#607D8B,color:#263238;
    classDef orch fill:#E3F2FD,stroke:#64B5F6,color:#0D47A1;
    classDef bridge fill:#FFF3E0,stroke:#FFB74D,color:#E65100;
```
