Packages
macula
0.6.4
7.0.0
6.0.0
5.2.2
5.2.1
5.2.0
5.1.0
5.0.0
4.8.0
4.7.1
4.7.0
4.6.0
4.5.0
4.4.10
4.4.9
4.4.8
4.4.7
4.4.6
4.4.5
4.4.4
4.4.3
4.4.2
4.4.1
4.4.0
4.3.1
4.3.0
4.2.9
4.2.8
4.2.7
4.2.6
4.2.5
4.2.4
4.2.3
4.2.2
4.2.1
4.2.0
4.1.1
4.1.0
4.0.0
3.16.0
3.15.3
3.15.2
3.15.1
3.14.0
3.13.0
3.12.1
3.12.0
3.11.1
3.11.0
3.10.3
3.10.2
3.10.1
3.9.0
3.8.0
3.7.0
3.5.0
3.4.0
3.3.0
3.2.0
3.1.0
3.0.0
2.1.1
2.1.0
2.0.0
1.5.2
1.5.1
1.4.30
1.4.29
1.4.28
1.4.27
1.4.26
1.4.25
1.4.24
1.4.23
1.4.22
1.4.21
1.4.20
1.4.19
1.4.18
1.4.17
1.4.16
1.4.15
1.4.14
1.4.13
1.4.11
1.4.10
1.4.9
1.4.8
1.4.7
1.4.6
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
1.3.1
1.3.0
1.2.0
1.1.0
1.0.10
1.0.9
1.0.8
1.0.7
1.0.6
1.0.5
1.0.4
1.0.3
1.0.2
1.0.1
1.0.0
0.48.6
0.48.5
0.48.4
0.48.3
0.48.2
0.48.1
0.48.0
0.47.1
0.47.0
0.46.3
0.46.1
0.46.0
0.45.3
0.45.2
0.45.1
0.45.0
0.44.2
0.44.1
0.44.0
0.43.3
0.43.2
0.43.1
0.43.0
0.42.9
0.42.8
0.42.7
0.42.6
0.42.5
0.42.4
0.42.3
0.42.2
0.42.1
0.42.0
0.41.1
0.41.0
0.40.1
0.40.0
0.39.9
0.39.8
0.39.7
0.39.6
0.39.5
0.39.4
0.39.3
0.39.2
0.39.1
0.39.0
0.38.8
0.38.7
0.38.6
0.38.5
0.38.4
0.38.3
0.38.2
0.38.1
0.38.0
0.37.7
0.37.6
0.37.5
0.37.4
0.37.3
0.37.2
0.37.1
0.37.0
0.36.6
0.36.5
0.36.4
0.36.3
0.36.2
0.36.1
0.36.0
0.35.4
0.35.3
0.35.2
0.35.1
0.35.0
0.34.1
0.34.0
0.33.1
0.33.0
0.32.5
0.32.4
0.32.3
0.32.2
0.32.1
0.32.0
0.31.9
0.31.8
0.31.7
0.31.6
0.31.5
0.31.4
0.31.3
0.31.2
0.31.1
0.31.0
0.30.10
0.30.9
0.30.8
0.30.7
0.30.6
0.30.5
0.30.4
0.30.3
0.30.2
0.30.1
0.30.0
0.29.0
0.28.3
0.28.2
0.28.1
0.28.0
0.27.1
0.27.0
0.26.1
0.26.0
0.25.6
0.25.5
0.25.4
0.25.3
0.25.2
0.25.1
0.25.0
0.24.6
0.24.5
0.24.4
0.24.3
0.24.2
0.24.1
0.24.0
0.23.3
0.23.2
0.23.1
0.23.0
0.22.12
0.22.11
0.22.10
0.22.9
0.22.8
0.22.7
0.22.6
0.22.5
0.22.4
0.22.3
0.22.2
0.22.1
0.22.0
0.21.7
0.21.6
0.21.5
0.21.4
0.21.2
0.21.1
0.21.0
0.20.25
0.20.24
0.20.23
0.20.22
0.20.21
0.20.20
0.20.19
0.20.18
0.20.17
0.20.16
0.20.15
0.20.14
0.20.13
0.20.12
0.20.11
0.20.10
0.20.9
0.20.8
0.20.7
0.20.6
0.20.5
0.20.3
0.20.2
0.20.1
0.20.0
0.19.2
0.19.1
0.19.0
0.18.1
0.18.0
0.17.4
0.17.3
0.17.2
0.17.1
0.17.0
0.16.6
0.16.5
0.16.4
0.16.3
0.16.2
0.16.1
0.16.0
0.15.1
0.15.0
0.14.3
0.14.2
0.14.1
0.14.0
0.12.6
0.12.5
0.12.3
0.11.3
0.10.2
0.10.1
0.10.0
0.9.2
0.9.1
0.9.0
0.8.25
0.8.24
0.8.23
0.8.22
0.8.21
0.8.20
0.8.19
0.8.18
0.8.17
0.8.16
0.8.15
0.8.14
0.8.13
0.8.12
0.8.11
0.8.10
0.8.9
0.8.8
0.8.7
0.8.6
0.8.5
0.8.4
0.8.3
0.8.2
0.8.1
0.8.0
0.7.30
0.7.29
0.7.28
0.7.27
0.7.26
0.7.25
0.7.24
0.7.23
0.7.22
0.7.21
0.7.20
0.7.19
0.7.18
0.7.17
0.7.16
0.7.15
0.7.14
0.7.13
0.7.12
0.7.11
0.7.10
0.7.9
0.7.8
0.7.7
0.7.6
0.7.5
0.7.4
0.7.3
0.7.2
0.7.1
0.7.0
0.6.7
0.6.6
0.6.5
0.6.4
0.6.3
0.6.2
0.6.1
0.6.0
0.5.0
0.4.4
0.4.3
0.4.2
0.4.1
0.4.0
0.3.4
0.3.3
0.3.2
0.3.1
Macula HTTP/3 Mesh SDK — connect, subscribe, publish, call, advertise
Current section
Files
Jump to
Current section
Files
README.md
<div align="center">
<img src="artwork/macula-logo-color.svg" alt="Macula Logo" width="500"/>
<h1>Macula HTTP/3 Mesh</h1>
<p><em>A distributed platform for decentralized applications</em></p>
</div>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"/></a>
<a href="https://www.erlang.org"><img src="https://img.shields.io/badge/Erlang%2FOTP-26+-brightgreen" alt="Erlang/OTP"/></a>
</p>
---
## Architecture Overview
```mermaid
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
```
---
## Table of Contents
📖 **[Executive Summary](docs/EXECUTIVE_SUMMARY.md)** - What Macula is and why it matters
🚀 **[Quick Start](architecture/macula_http3_mesh_quick_start.md)** - Get running in 15 minutes
💡 **[Hello World Tutorial](HELLO_WORLD.md)** - Build a distributed chat app in 30 minutes
📚 **[Technical Documentation](architecture/macula_http3_mesh_root.md)** - Complete architecture and implementation guides
🔧 **[Development Guide](docs/DEVELOPMENT.md)** - Setup, testing, and contributing
🏗️ **[Comparisons](docs/COMPARISONS.md)** - How Macula compares to similar systems
📊 **[Use Cases](docs/USE_CASES.md)** - Real-world applications and examples
📝 **[Project Structure](architecture/MACULA_PROJECT_STRUCTURE.md)** - Module organization and dependencies
🗺️ **[Roadmap](architecture/macula_http3_mesh_roadmap.md)** - 20-week implementation plan
📄 **[Changelog](CHANGELOG.md)** - Version history and migration guides
---
## What is Macula?
Macula is infrastructure for building **decentralized applications and services** that operate autonomously at the edge, without dependency on centralized cloud infrastructure.
**Key Features:**
✅ **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)
---
## Installation
**Elixir (mix.exs):**
```elixir
def deps do
[
{:macula, git: "https://github.com/macula-io/macula.git", branch: "main"}
]
end
```
**Erlang (rebar.config):**
```erlang
{deps, [
{macula, {git, "https://github.com/macula-io/macula.git", {branch, "main"}}}
]}.
```
---
## Development Setup
```bash
# 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
```
---
## Contributing
We welcome contributions! See [Development Guide](docs/DEVELOPMENT.md) for setup instructions and [Contributing Guide](CONTRIBUTING.md) for guidelines.
---
## License
Macula is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.
---
## Community & Support
- **Issues**: [GitHub Issues](https://github.com/macula-io/macula/issues)
- **Documentation**: [Architecture Docs](architecture/)
- **Examples**: [Examples Directory](examples/)
---
**Built with ❤️ for the BEAM community**