Modulr.Core

Overview

Modulr.Core is the foundational routing and coordination layer of the Modulr network.

It is responsible for connecting users, modules, and services through a unified, signed message protocol. Rather than acting as a traditional centralized server, Modulr.Core serves as a network entry point and discovery layer, allowing participants to locate and interact with other modules such as storage, assets, and compute services.

This repository contains the reference implementation of the Core module for the Modulr ecosystem.

---

What is Modulr?

Modulr is a modular, decentralized system designed to function as a next-generation internet platform.

Instead of relying on monolithic services, Modulr is composed of independent modules such as:

• modulr.core — routing, identity, and discovery
• modulr.assets — balances, ownership, and asset protection
• modulr.storage — distributed storage coordination

Each module operates independently while communicating through a shared protocol.

---

Responsibilities of Modulr.Core

Modulr.Core acts as the coordination plane of the network.

It is responsible for:

• Identity Verification Validating signed requests from users, modules, and services.
• Module Registration Allowing new modules (e.g. modulr.storage, modulr.assets) to join the network.
• Module Lookup & Routing Resolving where modules live and how to communicate with them.
• Naming System Registering and resolving human-readable names for:
  • users
  • organizations
  • modules
• Organization Management Supporting organization-based ownership and collaboration.
• Protocol Discovery Providing version and capability information for the network.
• Network Status Receiving heartbeat updates from modules and tracking availability.

---

What Modulr.Core Does NOT Do

To maintain scalability and modularity, Modulr.Core does not handle:

• storage logic (modulr.storage)
• asset balances or payments (modulr.assets)
• provider payouts
• application-specific functionality

Those responsibilities belong to their respective modules.

---

Architecture

Modulr follows a modular service architecture:

Client → Modulr.Core → Target Module

Example flow:

1. A client sends a request to modulr.core
2. Core resolves the route to a target module (e.g. modulr.storage)
3. The client communicates directly with that module

Core is not a bottleneck — it is a router and registry, not a data processor.

---

Message Protocol

All communication in Modulr is performed using a signed, versioned message envelope.

Key Concepts

• Protocol Versioning Format: YYYY.MM.DD.N
• Target Module Specifies which module should process the request
• Operation-Based Execution Each request calls a specific operation (function) on a module
• Signed Requests Every request is authenticated using cryptographic signatures

Example Message

{
  "protocol_version": "2026.03.22.0",
  "message_id": "msg-001",
  "target_module": "modulr.core",
  "target_module_version": null,
  "operation": "lookup_module",

  "sender_id": "user:abc123",
  "sender_key_type": "ed25519",
  "sender_public_key": "PUBKEY_HERE",

  "timestamp": "2026-03-22T23:10:00Z",
  "expires_at": "2026-03-22T23:11:00Z",

  "payload": {
    "module_name": "modulr.storage"
  },
  "payload_hash": "HASH_HERE",

  "signature_algorithm": "ed25519",
  "signature": "SIG_HERE"
}

---

Bootstrap Phase

During initial network bring-up, Modulr.Core uses a bootstrap authority set.

Bootstrap authorities are trusted identities that can:

• register initial modules
• register organizations
• publish protocol definitions

These privileges are time-limited

---

Operations (V1)

The following operations are part of the initial Core implementation:

• get_protocol_version
• get_protocol_methods
• get_module_methods
• lookup_module
• register_module
• register_org
• register_name
• resolve_name
• reverse_resolve_name
• heartbeat_update
• submit_module_route
• remove_module_route
• get_module_route

---

Development Philosophy

Modulr.Core is designed to be:

• Minimal — only handles coordination logic
• Modular — everything else is delegated
• Replaceable — individual modules can be rewritten in any language
• Protocol-Driven — behavior is defined by message structure, not framework choice

---

Implementation Notes

The initial implementation is expected to:

• use Python for rapid iteration
• expose HTTP endpoints (FastAPI recommended)
• validate signed message envelopes
• enforce strict input validation and limits

Future implementations may migrate components to:

• Rust (performance-critical paths)
• Go (network services)
• other languages as needed

---

Status

This project is currently in early development.

The focus is on:

• protocol stability
• message validation
• module registration and routing
• foundational network behavior

---

Development

Python 3.11+ required. Runtime dependencies (including cryptography for Ed25519) are listed in pyproject.toml; pip install -e ".[dev]" installs them into your venv.

Use a virtual environment so dependencies stay isolated from your system Python. Create it once per clone (the .venv folder is gitignored and is not part of the repo).

Windows (PowerShell or cmd):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

If PowerShell refuses to run Activate.ps1, use cmd and run .venv\Scripts\activate.bat, or allow scripts for your user once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Then run checks from the repo root (with the venv still activated):

ruff check src tests
ruff format --check src tests
pytest

The importable package is modulr_core; the protocol module name on the wire remains modulr.core.

Run the HTTP server (local)

The modulr-core command only works after the package is installed into your venv. From the repository root (with .venv activated):

pip install -e ".[dev]"
modulr-core --config dev.toml

Use modulr-core -v --config dev.toml when you want each request logged (method, path, Origin, status) plus a startup list of routes. GET /version returning 404 almost always means the server process is still on old code — stop it and start again (and run pip install -e ".[dev]" if you pulled changes).

Defaults: 127.0.0.1:8000. Override with --host / --port. If you see ModuleNotFoundError: No module named 'modulr_core', the editable install is missing or the venv is wrong — run pip install -e ".[dev]" again from this repo’s root.

A config file is required: use --config dev.toml or set MODULR_CORE_CONFIG to a TOML path. If the port is already taken, the CLI exits with a short error before starting uvicorn.

Read-only: GET /version returns JSON target_module and version (for UI connectivity). In dev_mode, CORS allows the local customer UI origins unless MODULR_CORE_CORS_ORIGINS is set (comma-separated list).

Customer web UI (stage 1)

A Next.js app in frontend/ is the customer-facing shell (theme blend, glass layout, firefly/gradient backgrounds, settings for Modulr.Core URLs). It is kept beside Core for convenience and is expected to move to its own repository later.

cd frontend
npm install
npm run dev

Details: frontend/README.md. Phased product plan: plan/customer_web_interface.md.

---

License

BSL - Business Specific License

---

Final Notes

Modulr.Core is the foundation of the Modulr network and is needed to communicate and connect to other modules on the network