Macula Logo

Macula HTTP/3 Mesh

A distributed platform for decentralized applications

LicenseErlang/OTP

Architecture Overview

graph TB

    subgraph "Macula HTTP/3 Mesh Network"

        subgraph "Gateway Node (Registry)"

            GW[Gateway<br/>• Service Registry<br/>• DHT Routing<br/>• Kademlia]

        end



        subgraph "Edge Nodes"

            E1[Edge Node 1<br/>• Pub/Sub<br/>• RPC Client<br/>• Service Provider]

            E2[Edge Node 2<br/>• Pub/Sub<br/>• RPC Client<br/>• Service Provider]

            E3[Edge Node 3<br/>• Pub/Sub<br/>• RPC Client<br/>• Service Provider]

        end



        subgraph "IoT Devices"

            IOT1[IoT Device 1]

            IOT2[IoT Device 2]

        end

    end



    DEV[Application Developer<br/>Erlang/Elixir Apps]



    INTERNET[Internet<br/>HTTP/3 over QUIC<br/>NAT/Firewall Friendly]



    DEV -->|Builds on| GW

    DEV -->|Deploys to| E1

    DEV -->|Deploys to| E2

    DEV -->|Deploys to| E3



    E1 <-->|HTTP/3| INTERNET

    E2 <-->|HTTP/3| INTERNET

    E3 <-->|HTTP/3| INTERNET

    GW <-->|HTTP/3| INTERNET

    IOT1 <-->|HTTP/3| INTERNET

    IOT2 <-->|HTTP/3| INTERNET



    E1 -.->|DHT Lookup| GW

    E2 -.->|DHT Lookup| GW

    E3 -.->|DHT Lookup| GW

    IOT1 -.->|DHT Lookup| GW

    IOT2 -.->|DHT Lookup| GW



    E1 <-.->|Pub/Sub & RPC| E2

    E2 <-.->|Pub/Sub & RPC| E3

    E3 <-.->|Pub/Sub & RPC| E1

    E1 <-.->|Pub/Sub & RPC| IOT1

    E2 <-.->|Pub/Sub & RPC| IOT2



    style GW fill:#4a90e2,stroke:#2e5c8a,color:#fff

    style E1 fill:#50c878,stroke:#2d7a4a,color:#fff

    style E2 fill:#50c878,stroke:#2d7a4a,color:#fff

    style E3 fill:#50c878,stroke:#2d7a4a,color:#fff

    style IOT1 fill:#9b59b6,stroke:#6c3483,color:#fff

    style IOT2 fill:#9b59b6,stroke:#6c3483,color:#fff

    style DEV fill:#f39c12,stroke:#b8730a,color:#fff

    style INTERNET fill:#ecf0f1,stroke:#95a5a6,color:#333

Executive Summary

Macula is infrastructure for building decentralized applications and services that operate autonomously at the edge, without dependency on centralized cloud infrastructure. It enables organizations to build systems where business logic, data, and intelligence live close to where they're needed—whether that's in factories, homes, vehicles, or partner networks.

Key Use Cases:

Unlike traditional architectures where applications call centralized APIs, Macula enables peer-to-peer mesh networks where nodes discover each other, share services, and collaborate directly. Data stays where it's created, intelligence adapts locally, and the network self-organizes without central coordination.

Built on HTTP/3 (QUIC) transport, Macula works through NAT and firewalls, making it practical for real-world deployments across diverse network environments.

Why Macula? The Case for Decentralization

The Centralized Cloud Problem

Today's applications typically rely on centralized cloud platforms controlled by Big Tech companies (AWS, Azure, Google Cloud). While this model offers convenience, it creates fundamental issues:

The Macula Alternative

Macula offers a different approach that complements or replaces centralized cloud:

Macula isn't anti-cloud—it's about choice. Use the cloud where it makes sense, but don't let it be your only option. Build applications that work in hybrid environments, can migrate between deployment models, and give you control over your technology destiny.

For organizations that value autonomy, data sovereignty, and resilience, Macula provides the infrastructure to build truly decentralized systems.

How Macula Compares to Similar Systems

Distributed networking is not new, and several excellent projects tackle similar problems. Here's how Macula differs:

vs. libp2p (IPFS Networking Stack)

libp2p is the modular networking stack behind IPFS and Filecoin.

vs. Distributed Erlang

Distributed Erlang is Erlang's built-in clustering.

vs. Akka Cluster (JVM)

Akka Cluster provides distributed actor systems for the JVM.

vs. Kubernetes (Orchestration)

Kubernetes orchestrates containerized applications at scale.

vs. WebRTC (Browser P2P)

WebRTC enables peer-to-peer communication in web browsers.

Macula's Unique Position

Macula combines ideas from these systems but targets a specific niche:

✅ BEAM-native (Erlang/Elixir OTP supervision and fault tolerance) ✅ HTTP/3 (QUIC) transport (modern, encrypted, NAT-friendly) ✅ Edge-first design (works through firewalls and NAT) ✅ Built-in pub/sub & RPC (no external message broker needed) ✅ Multi-tenancy (realm isolation for SaaS and shared infrastructure) ✅ Self-organizing mesh (DHT-based service discovery, O(log N) routing) ✅ Production-ready patterns (OTP behaviors, comprehensive testing, memory management)

If you're building decentralized Erlang/Elixir applications that need to work in real-world network conditions (edge, IoT, hybrid cloud), Macula provides the infrastructure layer you need.

Quick Start

Want to build something immediately? 👉 Hello World Tutorial - Build a distributed chat app in 30 minutes!

Library Development Setup

# Clone the repository

git clone https://github.com/macula-io/macula.git

cd macula



# Fetch dependencies

rebar3 get-deps



# Compile

rebar3 compile



# Run tests

rebar3 eunit



# Start a shell with Macula loaded

rebar3 shell

Using Macula in Your Application

Elixir (mix.exs):

def deps do

  [

    {:macula, git: "https://github.com/macula-io/macula.git", branch: "main"}

  ]

end

Erlang (rebar.config):

{deps, [

    {macula, {git, "https://github.com/macula-io/macula.git", {branch, "main"}}}

]}.

See our Quick Start Guide for detailed instructions on setting up a multi-node mesh.

Architecture

Macula is a single Erlang/OTP library you add as a dependency to your applications. It provides ~68 modules organized into functional areas:

Protocol & Transport:

Mesh Networking:

Application Primitives:

Core Utilities:

Simply add Macula to your rebar.config or mix.exs and start using pub/sub and RPC in your applications.

See Project Structure for complete module documentation.

Documentation

📚 Start Here: Documentation Root

Essential Reading

Key Architecture Documents

See Documentation Status for full inventory.

Development Status

Current Phase: Foundation (Weeks 1-4)

Completion:

Dependencies:

Use Cases

Business Applications

IoT & Edge Computing

Adaptive & Collaborative AI

Contributing

We welcome contributions! See Contributing Guide for guidelines.

Focus Areas:

License

Macula is licensed under the Apache License 2.0. See LICENSE for details.

Community & Support

Built with ❤️ for the BEAM community