> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v2.ard.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> ModMS system architecture and component details

## Architecture Diagram

<Frame>
  <img src="https://mintcdn.com/ardlabs/3ku9FDhvWhMgos-x/images/modms/architecture.png?fit=max&auto=format&n=3ku9FDhvWhMgos-x&q=85&s=41c3b980cec3e28a04a85fe2bfc27e6e" alt="ModMS system architecture showing Aggregator, Indexer, Server, and Receiver components with data flow" width="1168" height="941" data-path="images/modms/architecture.png" />
</Frame>

## Components

<Tabs>
  <Tab title="Aggregator">
    The data ingestion component responsible for downloading and preprocessing model data.

    **Responsibilities:**

    * Downloads models according to schedule
    * Performs model-specific post-processing on GRIB files
    * Notifies the indexer when new files are ready
    * Must be on the same server as the indexer to share the filesystem

    <Warning>
      The Aggregator and Indexer must run on the same server to share the filesystem for efficient data transfer.
    </Warning>
  </Tab>

  <Tab title="Indexer">
    The data processing component that converts and prepares data for storage.

    **Responsibilities:**

    * Creates NetCDF files from GRIB files
    * Copies output files to GlusterFS mountpoint
    * Notifies the server of new model runs
    * Responsible for naming variables consistently

    <Note>
      Variable naming is critical for API queries. Ensure variables are properly defined in `grib[12].csv` files.
    </Note>
  </Tab>

  <Tab title="Server">
    The API service that provides flexible querying capabilities for model data.

    **Capabilities:**

    * Provides a flexible API to query models
    * Can plot maps in custom styles
    * Supports custom functions and mathematical expressions in queries
    * Handles multiple concurrent requests

    **Query Features:**

    * **Spatial queries**: Geographic regions
    * **Temporal queries**: Time ranges
    * **Variable-specific queries**: Filter by specific model variables
    * **Mathematical expressions**: Aggregations and calculations
    * **Custom visualization styles**: Custom map plotting
  </Tab>

  <Tab title="Receiver">
    A push-based ingestion component for external data sources.

    **Functionality:**

    * Provides an HTTP endpoint to push new model runs
    * Used for systems like APOLLO that need to inject data directly
    * Bypasses the normal download schedule for real-time data ingestion

    <Note>
      The Receiver is particularly useful for integrating with external systems that generate model data on-demand.
    </Note>
  </Tab>
</Tabs>

## Data Flow

<Steps>
  <Step title="Data Download">
    The Aggregator downloads model data from external sources according to schedule.
  </Step>

  <Step title="Preprocessing">
    Model-specific post-processing is applied to GRIB files.
  </Step>

  <Step title="Conversion">
    The Indexer converts GRIB files to NetCDF format for efficient storage and querying.
  </Step>

  <Step title="Storage">
    Processed files are copied to the GlusterFS distributed storage system.
  </Step>

  <Step title="Indexing">
    The Indexer notifies the Server of new model runs available for querying.
  </Step>

  <Step title="Serving">
    The Server makes the data available through its flexible API.
  </Step>
</Steps>

## Storage Architecture

ModMS uses **GlusterFS** for distributed storage, providing:

<Columns>
  <Column>
    **Replication**

    Data is replicated across multiple nodes for redundancy
  </Column>

  <Column>
    **Consistency**

    Maintains consistent state across different servers
  </Column>

  <Column>
    **Scalability**

    Easy to add new storage nodes as data grows
  </Column>

  <Column>
    **High Availability**

    Automatic failover in case of node failures
  </Column>
</Columns>

<Warning>
  The GlusterFS mountpoint at `/data` must be properly configured and accessible. If issues occur, see the [FAQ](/data-ai/modms/faq) for troubleshooting steps.
</Warning>

## Servers & environments

<Tabs>
  <Tab title="Core ModMS nodes">
    Typical ModMS deployment uses:

    * `n01.modms.devops.arabiaweather.com`
    * `n02.modms.devops.arabiaweather.com`
    * `indexer.modms.devops.arabiaweather.com` (Indexer server)

    These nodes share the GlusterFS volume mounted at `/data` and host the Aggregator, Indexer, and Server components.
  </Tab>

  <Tab title="File storage">
    All ModMS nodes must have:

    * GlusterFS peers in **Connected** state
    * The volume mounted at `/data`

    For operational commands and troubleshooting, see:

    * [Why GlusterFS is used](/data-ai/modms/faq/why-glusterfs)
    * [Mountpoint `/data` not working](/data-ai/modms/faq/mountpoint-not-working)
  </Tab>
</Tabs>

## GlusterFS Architecture Details

ModMS uses a replicated GlusterFS volume with:

* Multiple brick nodes for data storage
* Arbiter node for split-brain prevention
* Self-healing daemon for automatic recovery
* TCP transport for network communication

## Performance Considerations

<AccordionGroup>
  <Accordion title="Server Startup Time">
    The server scans all NetCDF files at startup, which can take approximately **3 minutes** with large datasets.

    <Note>
      For cold starts, it's recommended to start with 2 container replicas and scale up once ready.
    </Note>
  </Accordion>

  <Accordion title="File System Requirements">
    The Aggregator and Indexer must share a filesystem, requiring them to run on the same server.
  </Accordion>

  <Accordion title="Storage Optimization">
    NetCDF format is used for efficient querying and reduced storage overhead compared to raw GRIB files.
  </Accordion>
</AccordionGroup>