# Platform Architecture

A high-level map of how Monad is put together, aimed at operators running Monad in their own cluster. It covers the main components, how data moves through them, and where to look first when something is not working.

This is the starting point for running Monad yourself. Once you understand the components below, see [Installation With Helm](/docs/guides/customer_helm_install) to deploy them, and [Troubleshooting](/docs/guides/troubleshooting) when something is not working.

## Overview

Monad runs as a set of services on Kubernetes, deployed into a single namespace. At a high level there are three kinds of things in the diagram below:

- **Monad services**: the workloads that make up the control plane and run your pipelines.
- **Supporting infrastructure**: the datastores and networking Monad depends on. Some of these are open-source components deployed alongside Monad; others are provided by your cluster or cloud.
- **Customer data pipelines**: the pods that actually move your data, created on demand from the pipelines you build.

![Monad platform architecture: client traffic enters through a load balancer and gateway to the Monad services, which sit in front of supporting datastores and the pipeline pods that connect out to external sources and destinations](/img/guides/architecture/platform-architecture.png)

The ingress layer in this diagram (a cloud load balancer in front of an Istio gateway) shows one example setup. The load balancer and gateway are not part of Monad itself, so what you run depends on how you configured your install. See [Installation With Helm](/docs/guides/customer_helm_install) for the options.

## Monad services

These are the services Monad deploys. You can see them with:

```bash
kubectl get pods -n <namespace>
```

Throughout this guide, `<namespace>` is the namespace Monad was installed into.

| Component | Role |
| --- | --- |
| **UI** | The web interface where you build pipelines, manage connectors, and view status. |
| **API** | The REST control plane behind the UI and the [public API](/api). Everything the UI does goes through it. |
| **Pipeline Data Ingest** | The entry point for push-based inputs such as HTTP, OTLP, Splunk HEC, and syslog. It authenticates incoming data and hands it to the right pipeline. |
| **Docs** | Serves this documentation site inside your deployment. |
| **Operator** | Watches your pipeline definitions and reconciles them into the running pipeline pods, scaling and CronJob resources. This is the component that turns a pipeline you save in the UI into workloads in the cluster. |
| **Alert Service** | Evaluates alert conditions against pipeline metrics and publishes alerts when they fire or resolve. |

Each service is an independent Deployment, so you can inspect, restart, and read logs from them individually.

## Customer data pipelines

When you build and enable a pipeline, the Operator creates pods to run it. A pipeline is made up of four kinds of stages, which run as their own workloads:

| Stage | What it does |
| --- | --- |
| **Input** | Pulls data from a source, or receives pushed data, and brings it into the pipeline. |
| **Enrichment** | Adds context to each record (geolocation, threat intel, lookups, and so on). |
| **Transform** | Reshapes records by renaming fields, formatting values, filtering, and similar operations. |
| **Output** | Delivers records to a destination such as object storage, a SIEM, or a data warehouse. |

Stages hand records to each other through Monad's internal message queue, which durably buffers data so a slow or unavailable destination applies back-pressure rather than dropping records. For the delivery guarantees this provides, see [Reliability & Delivery](/docs/guides/reliability).

Pipeline pods scale independently based on load, so a busy pipeline will show more replicas than a quiet one. They are labeled by the pipeline they belong to, which makes it straightforward to find the pods for a specific pipeline when troubleshooting.

## Supporting infrastructure

Monad relies on a small set of datastores and networking components. These are standard, widely used pieces of infrastructure. You can see them running in the namespace, but you do not interact with them directly during normal use.

| Component | Purpose |
| --- | --- |
| **Ingress (gateway or ingress controller) and load balancer** | Terminate TLS and route external traffic to the right Monad service. Web traffic and push inputs both enter here. Monad does not ship these: you provide a Gateway API implementation or ingress controller, and the load balancer in front of it is whatever your cluster or cloud provisions for that ingress. The exact components depend on how you configured your install, so check your own gateway, ingress, and load balancer resources. See [Installation With Helm](/docs/guides/customer_helm_install) for how routing is configured. |
| **Message queue (NATS JetStream)** | The backbone that carries records between pipeline stages and provides the durable buffering behind back-pressure. |
| **Database (PostgreSQL)** | Stores your configuration: organizations, users, pipelines, connectors, and settings. Can be the bundled operator-managed instance or [an external database](/docs/guides/customer_helm_install#external-postgres). |
| **Memory cache (Dragonfly)** | An in-memory cache used to speed up frequently accessed data. |
| **Metrics store (Victoria Metrics)** | Backs the metrics Monad shows in the API and UI, such as pipeline volume, throughput, and health, and feeds status indicators and alerting. This is a datastore for Monad's own product metrics, not an infrastructure observability system. To monitor the cluster itself, use your own observability stack. |
| **Kubernetes API** | The Operator talks to the cluster's Kubernetes API to create and manage pipeline workloads. |

Monad components communicate with these dependencies over the cluster network. Your data leaves the cluster only when a pipeline reaches out to your configured sources and destinations (the **external sources** in the diagram), or when Monad pulls the reference data used by certain enrichments.

## How data flows

There are two paths worth understanding separately.

**Control traffic** (managing the platform): a user, or an API client, reaches the load balancer and gateway, which route to the UI, API, or Docs. When you save a pipeline, the API records it and the Operator reconciles it into running pipeline pods.

**Pipeline data** (your security data): records enter either by an input pulling from a source or by a client pushing into Pipeline Data Ingest. From there each record flows through the pipeline's stages (enrichment and transform as configured) over the message queue, and finally an output delivers it to your destination. Metrics about this flow are recorded throughout so you can see volume and health in the UI.

## Troubleshooting

Because Monad runs as ordinary Kubernetes workloads, most issues can be diagnosed with standard `kubectl` commands against the components described above. For a symptom-by-symptom guide to diagnosing a self-managed deployment, see [Troubleshooting](/docs/guides/troubleshooting).