Documentation hub for the Macula distributed application platform
Macula is a BEAM-native platform for building distributed, event-sourced applications that run on a decentralized mesh network. The ecosystem combines:
- Event Sourcing - Capture every state change as an immutable event
- Mesh Networking - HTTP/3 over QUIC for NAT-friendly communication
- Edge Computing - Run workloads autonomously at the edge
- Neuroevolution - Evolve adaptive neural network controllers
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 platform comprises three distinct pillars, each addressing a core need:
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)
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.
Evolve adaptive neural network controllers using TWEANN and NEAT.
| Package | Description | Links |
|---|---|---|
| macula_tweann | Topology & Weight Evolving Artificial Neural Networks | GitHub | HexDocs |
| macula_neuroevolution | Full neuroevolution framework with populations and species | GitHub | HexDocs |
Core capabilities:
- NEAT Algorithm — NeuroEvolution of Augmenting Topologies
- Distributed Evaluation — Evolve populations across mesh nodes
- Speciation — Protect innovation through species-based selection
- Real-time Adaptation — Evolve controllers for dynamic environments
Reckon Ecosystem — Event Store & CQRS (reckon-db-org)
BEAM-native event sourcing infrastructure.
| Package | Description | Links |
|---|---|---|
| reckon_db | BEAM-native event store built on Khepri/Ra | GitHub | HexDocs |
| reckon_gater | Gateway for distributed event store access | GitHub | HexDocs |
| evoq | Event sourcing primitives (aggregates, commands, events) | GitHub | HexDocs |
| reckon_evoq | Adapter connecting Evoq to ReckonDB | GitHub | HexDocs |
Core capabilities:
- Raft Consensus — Strong consistency via Ra (Erlang Raft implementation)
- Event Replay — Full audit trail and time-travel debugging
- CQRS Patterns — Command/query separation with projections
- Distributed Clusters — Automatic discovery via LibCluster
- 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
- MaculaOS - Edge deployment
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
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
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
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
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
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
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
- 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 neuroevolution
- Healthcare - Decentralized patient data with UCAN authorization
- GitHub: macula-io | reckon-db-org | beam-campus
- Hex.pm: Search for
macula,reckon, orbc_gitops - Issues: Report bugs on the respective repositories
Apache 2.0 - See LICENSE for details.
Built with the BEAM
