<div align="center">
  <img src="artwork/macula-alt-logo.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>

---

## 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, "~> 0.6"}
  ]
end
```

**Erlang (rebar.config):**

```erlang
{deps, [
    {macula, "0.6.6"}
]}.
```

---

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