Macula Ecosystem

Documentation hub for the Macula distributed application platform

---

What is Macula?

Macula is a BEAM-native platform for building distributed applications that run on a decentralized mesh network. The ecosystem provides:

• Mesh Networking - HTTP/3 over QUIC for NAT-friendly communication
• Edge Computing - Run workloads autonomously at the edge
• Content Transfer - P2P artifact distribution without external dependencies
• GitOps Orchestration - Deploy and manage OTP applications across the mesh

Architecture Overview

Mesh Architecture

Edge nodes form clusters that participate in a realm (mesh). Services advertise to the Kademlia DHT, consumers discover them, and communication happens via RPC (request/response) or PubSub (broadcast). All interactions are secured with DID identities and UCAN capability tokens.

The Ecosystem

The Macula platform comprises the following components:

---

Macula Mesh — Decentralized Infrastructure

A BEAM-native HTTP/3 mesh network for edge computing.

Package	Description	Links
macula	HTTP/3 mesh networking over QUIC with DHT-based service discovery	GitHub | HexDocs
macula_console	Management console for Macula nodes and clusters	GitHub
macula_os	Immutable edge node operating system (based on k3os)	GitHub

Core capabilities:

• DHT PubSub — Decentralized publish/subscribe via Kademlia DHT
• DHT RPC — Request/response patterns with service discovery
• NAT Traversal — HTTP/3 over QUIC for firewall-friendly communication
• Capability Security — DID identities with UCAN authorization tokens

---

bc_gitops — Mesh Application Orchestration (beam-campus)

BEAM-native GitOps reconciler for publishing, installing, and managing OTP applications across the mesh.

Package	Description	Links
bc_gitops	GitOps reconciler for OTP applications	GitHub | HexDocs

Core capabilities:

• GitOps Reconciliation — Watches a Git repository for application specifications
• Auto-deployment — Automatically deploys, upgrades, and removes applications based on config changes
• Hot Code Reload — Supports hot code upgrades for same-version changes
• Dependency Management — Respects application dependencies during deployment
• Multi-format Config — Supports Erlang terms, YAML, and JSON config files
• Pluggable Runtime — Custom deployment strategies via runtime behaviour
• Mesh Source Type — Fetch releases from mesh via MCID (Macula Content Identifier)

---

Macula Content Transfer — P2P Artifact Distribution

BEAM-native content-addressed storage and transfer system for distributing OTP releases and artifacts across the mesh without external dependencies like IPFS or BitTorrent.

Core capabilities:

• Content-Addressed Storage — MCID (Macula Content Identifier) ensures same content = same ID everywhere
• Merkle Tree Verification — Chunk-level integrity verification with parallel download
• Want/Have/Block Protocol — Efficient P2P exchange inspired by IPFS Bitswap
• DHT Integration — Announce availability and discover providers via Kademlia DHT
• Parallel Download — Fetch chunks from multiple providers simultaneously
• NAT-Friendly — Uses existing Macula QUIC transport (no new NAT traversal needed)

Protocol message types: content_want, content_have, content_block, content_manifest_req, content_manifest_res, content_cancel

See the Content Transfer Guide for API usage and protocol details.

Data Flow

Documentation

• Overview - Introduction to the ecosystem
• Architecture - How the pieces fit together
• Getting Started - Build your first app
• Event Sourcing - CQRS/ES patterns
• Mesh Networking - HTTP/3 mesh guide
• Content Transfer - P2P artifact distribution
• Neuroevolution - TWEANN and NEAT (moved to Faber ecosystem)
• MaculaOS - Edge deployment

Related Ecosystems

Macula works alongside two independent ecosystems, each maintained by their own organizations:

Reckon — Event Sourcing & CQRS (reckon-db-org)

A BEAM-native event sourcing stack providing durable event stores, CQRS frameworks, and distributed persistence. Applications built on Macula can use Reckon for event-sourced state management.

Package	Description	Links
reckon_db	Distributed event store on Khepri/Ra	GitHub | HexDocs
evoq	CQRS/ES framework (aggregates, commands, events)	GitHub | HexDocs
reckon_gater	Gateway and shared types	GitHub | HexDocs
reckon_evoq	Adapter connecting evoq to ReckonDB	GitHub | HexDocs

See reckon-ecosystem for full documentation.

Hecate — AI-Powered Developer Studio (hecate-social)

An AI-powered developer studio for building applications on the Macula mesh. Hecate uses both Macula (for mesh networking) and Reckon (for event sourcing) to provide a venture lifecycle management system.

Component	Description	Links
hecate-daemon	Erlang/OTP backend with venture lifecycle and LLM providers	GitHub
hecate-web	Native desktop UI with Tauri/SvelteKit (DevOps, LLM, Event Storming)	GitHub
hecate-tui	Go terminal UI with chat, tools, and vim mode	GitHub
hecate-agents	Philosophy, skills, and code generation templates	GitHub

See hecate-ecosystem for full documentation.

Faber — AI & Neuroevolution (rgfaber)

Evolutionary neural network framework for Erlang/OTP. Evolve adaptive AI controllers using TWEANN and NEAT, with optional distributed evaluation across the Macula mesh.

Package	Description	Links
faber_tweann	TWEANN neural networks with LTC neurons and ONNX export	GitHub | HexDocs
faber_neuroevolution	Population-based evolutionary training with speciation and selection	GitHub | HexDocs

See faber-ecosystem for full documentation.

---

Why Macula?

Reclaim Your Place in the AI Economy

AI is rapidly automating cognitive work, displacing millions from traditional employment. But AI needs compute—and that's an opportunity. Macula transforms you from a displaced worker into an infrastructure provider:

• Compute as a new asset class - Your hardware becomes income-generating infrastructure
• Run micro-datacenters - Participate in the mesh economy from your home or office
• Own your contribution - No middleman taking 30%+ of your compute value
• Community-owned AI - Train and run models on community infrastructure, not Big Tech clouds

A Platform for Indies and Solo Developers

Big Tech platforms demand 30% cuts, dictate your terms, and can deplatform you overnight. Macula puts a production-ready distributed platform at your fingertips:

• Zero platform fees - Keep 100% of what you earn
• No app store gatekeepers - Deploy directly to your users
• Built-in distribution - Your app runs on the mesh, scales with demand
• Own your relationship - Direct connection to users, no algorithm deciding your fate

Break Free from Big Tech

Five companies control most cloud infrastructure, creating vendor lock-in and data exploitation. Macula provides infrastructure you own:

• Local data processing - Your data never leaves your network
• Open standards - No proprietary lock-in, no platform risk
• Portable workloads - Move freely between nodes and providers

Data Sovereignty by Design

Governments worldwide enforce strict data residency requirements (GDPR, CCPA, localization laws). Macula's edge-first architecture naturally complies:

• Processing where data is created - No cross-border transfers
• Cryptographic authorization - UCAN tokens, not central auth servers
• Audit trails - Event sourcing captures every state change

Digital Resilience

Centralized systems fail catastrophically. Macula's mesh architecture ensures continuity:

• If node A fails, nodes B, C, D continue - No single point of failure
• Offline-capable - Nodes operate independently when disconnected
• Eventual consistency - Changes propagate when connectivity returns

Environmental Efficiency

Data centers consume significant global electricity while operating at only 15-25% utilization. Edge processing changes this:

• 10x energy reduction for local processing vs cloud round-trips
• Utilize existing hardware - Any device can join the mesh
• Reduce network overhead - Process data where it's generated

BEAM-Native Excellence

Every component is built on the BEAM (Erlang VM), battle-tested in telecom for 40+ years:

• Fault tolerance - Supervisors restart failed processes automatically
• Soft real-time - Predictable latency characteristics
• Hot code loading - Deploy without downtime
• Massive concurrency - Millions of lightweight processes

Use Cases

• IoT Platforms - Collect and process sensor data at the edge
• Financial Systems - Complete audit trails with event sourcing
• Gaming - Real-time multiplayer on a mesh network
• Robotics - Evolve controllers with Faber neuroevolution
• Healthcare - Decentralized patient data with UCAN authorization

Community

• Macula: macula-io on GitHub | Search macula on hex.pm
• Reckon: reckon-db-org on GitHub | Search reckon on hex.pm
• Hecate: hecate-social on GitHub
• Faber: rgfaber on GitHub | Search faber on hex.pm
• beam-campus: beam-campus on GitHub | bc_gitops on hex.pm
• Issues: Report bugs on the respective repositories

License

Apache 2.0 - See LICENSE for details.

---

_{Built with the BEAM}