<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**
