Architecture

MoleSignal is one Rust binary that embeds the web application. The [node].roles setting decides which responsibilities a process carries. Two external services hold all durable state: PostgreSQL and object storage.

Components

Component	Responsibility
HTTP API and web UI	Port `5080`. Serves the product API, the embedded web application, `/metrics`, and the health endpoint.
Intake	Receives telemetry over HTTP and OTLP gRPC (`4317`), validates it, applies masking and pipelines, and writes it to the WAL and an in-memory buffer.
Write-ahead log (WAL)	Local, durable log of records that are not yet flushed. Replayed on start.
Object storage	Parquet data files, search index sidecars, sealed partition manifests, profile blobs, exports, and large Agent evidence.
PostgreSQL	Metadata: identities, organizations, streams and schemas, the file catalog, product resources, and job state.
Query engine	Apache DataFusion over Arrow. Runs SQL and PromQL-compatible queries, prunes files with catalog metadata and search indexes, and merges local and federated scans.
Search jobs	Durable asynchronous queries that querier nodes claim from PostgreSQL.
Compactor	Merges files, applies retention, and maintains the catalog, indexes, and object garbage.
Alert	Evaluates rules, drives escalations, renders scheduled reports, and runs connectors.
Probe runner	Executes synthetic monitors. A standalone node runs a built-in one, and external Probe Agents connect on ports `5084` and `5085`.
Mole Agent	Investigates issues through the shared tool catalog, with the permissions of the signed-in user.

There is no Kafka, Redis, or consensus service. Caches live in process memory and on local disk.

Runtime roles

The [node].roles setting composes one or more roles into the process:

Role	Main responsibility
`standalone`	All APIs, the web UI, and all workers in one process.
`router`	The full HTTP API and web UI, rate limiting, and forwarding of writes to intake nodes and of queries to querier nodes.
`intake`	Validation, pipelines, masking, WAL, buffers, and flush to Parquet.
`querier`	Query execution for requests that other nodes forward, and asynchronous search jobs.
`compactor`	File compaction, retention, and storage maintenance.
`alert`	Rule evaluation, schedules, escalation, delivery dispatch, and connectors.

The same binary and configuration model serve every role, and changing roles requires a restart. See Role-based deployment.

Data path

sender
  -> protocol receiver
  -> authentication + IAM
  -> schema / masking / pipeline
  -> WAL + Arrow buffer
  -> Parquet + search index
  -> object storage + catalog row in PostgreSQL

query
  -> planner + organization rewrite
  -> catalog and index pruning
  -> DataFusion / PromQL
  -> local or federated scan
  -> rows / NDJSON / async search job

A flush uploads the files first and records them in the catalog afterwards, then truncates the flushed WAL segments. A query reads the catalog to find the files that overlap its time range and stream, so only those files are fetched from object storage.

What lives where

Location	Content
PostgreSQL	Metadata and the file catalog.
Object storage	`artifacts/v1/...` data and index files, `manifests/v1/...` sealed partition manifests, `search_jobs/v1/...` results of search jobs, and other blobs such as profiles and session replays. Objects are grouped by organization, signal type, dataset, and time partition.
Local disk of an intake node	The WAL and, optionally, caches under `./data/cache`.

Streams and organizations are logical: a stream is a dataset in object storage and a row of metadata in PostgreSQL, and an organization is a prefix and a scope that the query planner enforces.

Background workers

Worker	Runs on	Default interval
Heartbeat, stale node sweep	Every node	5 seconds, 60 seconds
Object store health probe	Every node	30 seconds
Intake flush	`intake`	30 seconds or buffer threshold
Compaction and retention	`compactor`	300 seconds
Catalog sealing, index build, garbage collection, reconciliation	`compactor`	30 to 300 seconds
Alert evaluation and escalation dispatch	`alert`	30 seconds, 10 seconds
Scheduled reports	`alert`	Every 60 seconds a tick checks due reports
Search jobs	Nodes that serve the API	Claimed on demand
ACME issue and renewal	Nodes that terminate TLS	60 seconds, 6 hours
Self-telemetry collection	Every node	15 seconds for metrics

Ownership follows the selected role, so duplicate processes do not all perform the same job. Several compactor nodes divide their work by stream and by organization, and several alert nodes divide theirs by rule, report, pipeline, and connector. See Role-based deployment and Work division between alert nodes. See Configuration for every interval.

Authorization

Authentication produces an IAM context. Authorization reads database-backed permissions, roles, resource relationships, and explicit cross-organization grants. Resource handlers load the target, verify organization ownership, and authorize the requested action before a change. See Security and multi-tenancy.

Web application

The web application ships inside the binary and shares the HTTP port. The capability snapshot controls which menu items appear. A hidden item is still protected by the permission check of the backend.

Core concepts

Learn signals, streams, organizations, and storage.

Role-based deployment

Run roles in separate processes.

Get started

Data

Observe

Query and correlate

Reliability

AI ops

Collaboration

Admin

Deploy & operate

Best practices

Resources

Components

Runtime roles

Data path

What lives where

Background workers

Authorization

Web application

Core concepts

Role-based deployment

​Components

​Runtime roles

​Data path

​What lives where

​Background workers

​Authorization

​Web application

Core concepts

Role-based deployment

Components

Runtime roles

Data path

What lives where

Background workers

Authorization

Web application