# morpheusais/docs architecture

> Architecture diagram of the GitHub repository morpheusais/docs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/morpheusais/docs
- Repository: https://github.com/morpheusais/docs

## Overview

1. This repository is primarily a documentation and reference hub for the Morpheus ecosystem, not an application codebase. It organizes the project’s protocol design, tokenomics, contracts, guides, audits, and launch history in one place.

2. The top-level structure is audience-driven. The main functional partitions are:
   - Capital Providers
   - Code Providers
   - Compute Providers
   - FAQs & Guides
   - Morpheus Fundamentals
   - Smart Contracts
   - Security Audit Reports
   - Graphics and brand assets
   - Contributions and proof-of-contribution records

3. The `README.md` acts as the system overview. It defines Morpheus as “A Network For Powering Smart Agents” and frames the core product architecture as a local smart-agent experience plus Web3 infrastructure, with the important operating rule that agents do not hold private keys or autonomously execute transactions.

4. The protocol/economic layer is documented in the “Fundamentals” and “Capital Providers” sections. Key topics here are MOR tokenomics, emissions, burn mechanics, staking rewards, protection fund details, liquidity/AMM launch phases, and Techno Capital Machine concepts. These docs describe how capital flows into and out of the network and how participants are incentivized.

5. The smart-contract layer is explicitly separated under `Smart Contracts/`. The documented contracts include:
   - `Distribution`
   - `L1Sender`
   - `L2MessageReceiver`
   - `L2TokenReceiverV2`
   - `LinearDistributionIntervalDecrease`
   - `MOROFT`
   
   This suggests a multi-contract architecture that handles token distribution, cross-chain messaging, token transfers, and time-based reward schedules.

6. Cross-chain operation is a major boundary in the repository. The README lists MOR contract addresses on Ethereum, Arbitrum, and Base, and the docs include bridge/claim guides for both mainnet and testnet. The presence of L1/L2 sender and receiver contracts indicates a deliberate separation between canonical L1 logic and L2 token/reward handling.

7. The compute subsystem is documented separately under “Compute Providers.” It covers compute nodes, subnets, model registry, and the Morpheus/Lumerin model family. This part of the architecture represents the off-chain AI/inference side of the network: providers contribute compute capacity, and the docs define how those resources are identified, organized, and consumed.

8. The code-contributor subsystem is also distinct. “Code Providers” documents contribution weights, maintenance, best practices, and reference implementations. The contribution model is not just social; it is part of the protocol’s incentive architecture, with documented weighting and proof-of-contribution flows.

9. Operational user flows are captured in the guide collections. These include staking, rewards claiming, token swaps, wallet integration, testnet/mainnet walkthroughs, and developer setup guides for macOS and Windows. That makes the repo a procedural source of truth for both end users and operators interacting with the protocol.

10. The `Contributions/` folder formalizes recognition and rewards, especially for code, compute, and community work. This is part of the network’s governance/incentive boundary: contribution evidence is documented separately from the protocol specs.

11. `Security Audit Reports/` is a distinct trust and verification layer. It aggregates audits for the distribution contracts, L2 token receiver, MOR OFT token, builders, and related components. For architecture purposes, this folder is the assurance boundary for the on-chain subsystem.

12. `Archive/` and `Archive/Translations/` show that the repository is also a versioned knowledge base. Historical docs, prior testnet/mainnet guides, and multilingual translations are preserved as reference material rather than active system components.

13. `Graphics/` contains the visual/documentation asset pipeline: diagrams, logos, brand kits, and per-guide illustrations. These assets support the docs and user onboarding, but do not appear to affect runtime behavior.

14. The repo links out to the actual implementation repositories:
   - `moragents` for the local agent product
   - `SmartContracts` for contract code
   - `DashBoard` for the frontend dashboard
   - `Morpheus-Lumerin-Node` for compute infrastructure
   - `MOR20` for token contracts
   - `MRC` for request-for-comment/specification work
   
   So the architecture here is a documentation control plane over a distributed ecosystem of off-repo runtime components.

15. In diagram terms, the main boundaries are: documentation/specification, on-chain contracts, off-chain compute/agents, contribution accounting, and cross-chain token distribution. This repository describes how those pieces fit together, but it is not itself the execution environment.

Main entry points: [`README.md`](https://github.com/morpheusais/docs/blob/main/README.md) (README), [`Smart Contracts`](https://github.com/morpheusais/docs/tree/HEAD/Smart%20Contracts) (Smart Contracts), [`!KEYDOCS README FIRST!/Capital Providers, MOR20, TCM`](https://github.com/morpheusais/docs/tree/HEAD/!KEYDOCS%20README%20FIRST!/Capital%20Providers%2C%20MOR20%2C%20TCM) (Capital Providers), [`!KEYDOCS README FIRST!/FAQs & Guides`](https://github.com/morpheusais/docs/tree/HEAD/!KEYDOCS%20README%20FIRST!/FAQs%20%26%20Guides) (FAQs & Guides)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Documentation hub"]
  node_readme["README<br/>overview<br/>[README.md]"]
end

subgraph group_protocol["Protocol economics"]
  node_fundamentals["Fundamentals<br/>protocol docs"]
  node_capital["Capital Providers<br/>economic docs"]
end

subgraph group_providers["Provider systems"]
  node_codeprov["Code Providers<br/>contribution docs"]
  node_computeprov["Compute Providers<br/>compute docs"]
end

subgraph group_onchain["On-chain subsystem"]
  node_contracts["Smart Contracts<br/>contract docs"]
  node_audits["Audit Reports<br/>assurance"]
  node_distribution["Distribution<br/>contract<br/>[Distribution.md]"]
  node_l1sender["L1 Sender<br/>bridge contract<br/>[L1Sender.md]"]
  node_l2recv["L2 Receiver<br/>bridge contract"]
  node_l2token["L2 Token Receiver<br/>token contract"]
  node_linear["Interval Decrease<br/>reward schedule"]
  node_moft["MOROFT<br/>cross-chain token<br/>[MOROFT.md]"]
end

subgraph group_ops["Operations and support"]
  node_guides["FAQs & Guides<br/>user guides"]
  node_contrib["Contributions<br/>proof records"]
  node_archive["Archive<br/>historical docs"]
  node_graphics["Graphics<br/>brand assets"]
  node_multisig["Multisig Log<br/>ops log"]
  node_faqguides["Guide Collections<br/>workflow guides"]
end

node_readme -->|"frames"| node_fundamentals
node_readme -->|"organizes"| node_capital
node_readme -->|"organizes"| node_codeprov
node_readme -->|"organizes"| node_computeprov
node_readme -->|"links"| node_guides
node_readme -->|"separates"| node_contracts
node_readme -->|"trusts"| node_audits
node_readme -->|"records"| node_contrib
node_fundamentals -->|"informs"| node_capital
node_capital -->|"uses"| node_distribution
node_capital -->|"uses"| node_linear
node_capital -->|"centers on"| node_moft
node_contracts -->|"includes"| node_distribution
node_contracts -->|"includes"| node_l1sender
node_contracts -->|"includes"| node_l2recv
node_contracts -->|"includes"| node_l2token
node_contracts -->|"includes"| node_linear
node_contracts -->|"includes"| node_moft
node_guides -->|"contains"| node_faqguides
node_computeprov -->|"supports"| node_guides
node_codeprov -->|"feeds"| node_contrib
node_audits -->|"verifies"| node_contracts
node_archive -->|"preserves"| node_fundamentals
node_graphics -->|"supports"| node_guides
node_multisig -->|"tracks"| node_capital

click node_readme "https://github.com/morpheusais/docs/blob/main/README.md"
click node_fundamentals "https://github.com/morpheusais/docs/tree/main/!KEYDOCS README FIRST!/Morpheus Fundamentals"
click node_capital "https://github.com/morpheusais/docs/tree/main/!KEYDOCS README FIRST!/Capital Providers, MOR20, TCM"
click node_codeprov "https://github.com/morpheusais/docs/tree/main/!KEYDOCS README FIRST!/Code Providers"
click node_computeprov "https://github.com/morpheusais/docs/tree/main/!KEYDOCS README FIRST!/Compute Providers"
click node_guides "https://github.com/morpheusais/docs/tree/main/!KEYDOCS README FIRST!/FAQs & Guides"
click node_contracts "https://github.com/morpheusais/docs/tree/main/Smart Contracts"
click node_audits "https://github.com/morpheusais/docs/tree/main/Security Audit Reports"
click node_contrib "https://github.com/morpheusais/docs/tree/main/Contributions"
click node_archive "https://github.com/morpheusais/docs/tree/main/Archive"
click node_graphics "https://github.com/morpheusais/docs/tree/main/Graphics"
click node_multisig "https://github.com/morpheusais/docs/tree/main/MultisigLog"
click node_distribution "https://github.com/morpheusais/docs/blob/main/Smart Contracts/Distribution.md"
click node_l1sender "https://github.com/morpheusais/docs/blob/main/Smart Contracts/L1Sender.md"
click node_l2recv "https://github.com/morpheusais/docs/blob/main/Smart Contracts/L2MessageReceiver.md"
click node_l2token "https://github.com/morpheusais/docs/blob/main/Smart Contracts/L2TokenReceiverV2.md"
click node_linear "https://github.com/morpheusais/docs/blob/main/Smart Contracts/LinearDistributionIntervalDecrease.md"
click node_moft "https://github.com/morpheusais/docs/blob/main/Smart Contracts/MOROFT.md"
click node_faqguides "https://github.com/morpheusais/docs/tree/main/!KEYDOCS README FIRST!/FAQs & Guides/Guides"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme toneBlue
class node_fundamentals,node_capital toneAmber
class node_codeprov,node_computeprov toneMint
class node_contracts,node_audits,node_distribution,node_l1sender,node_l2recv,node_l2token,node_linear,node_moft toneRose
class node_guides,node_contrib,node_archive,node_graphics,node_multisig,node_faqguides toneIndigo
```

## Components

### Documentation hub

Primary reference and control-plane documentation for the Morpheus ecosystem.

- [README](https://github.com/morpheusais/docs/blob/main/README.md): overview · Top-level system overview for Morpheus as a smart-agent network. · `README.md`

### Protocol economics

Tokenomics, emissions, launch phases, and capital-provider mechanics.

- [Fundamentals](https://github.com/morpheusais/docs/tree/HEAD/!KEYDOCS%20README%20FIRST!/Morpheus%20Fundamentals): protocol docs · Core protocol concepts, freedoms, tokenomics, and launch framing. · `!KEYDOCS README FIRST!/Morpheus Fundamentals`
- [Capital Providers](https://github.com/morpheusais/docs/tree/HEAD/!KEYDOCS%20README%20FIRST!/Capital%20Providers%2C%20MOR20%2C%20TCM): economic docs · Capital-side tokenomics, AMM launch, liquidity, emissions, and TCM material. · `!KEYDOCS README FIRST!/Capital Providers, MOR20, TCM`

### Provider systems

Compute and code contribution models documented for the network.

- [Code Providers](https://github.com/morpheusais/docs/tree/HEAD/!KEYDOCS%20README%20FIRST!/Code%20Providers): contribution docs · Code contribution weights, best practices, and MRI reference material. · `!KEYDOCS README FIRST!/Code Providers`
- [Compute Providers](https://github.com/morpheusais/docs/tree/HEAD/!KEYDOCS%20README%20FIRST!/Compute%20Providers): compute docs · Off-chain inference, nodes, subnets, and model registry documentation. · `!KEYDOCS README FIRST!/Compute Providers`

### On-chain subsystem

Contract architecture, cross-chain handling, and assurance reports.

- [Smart Contracts](https://github.com/morpheusais/docs/tree/HEAD/Smart%20Contracts): contract docs · Documented on-chain contracts and their responsibilities. · `Smart Contracts`
- [Audit Reports](https://github.com/morpheusais/docs/tree/HEAD/Security%20Audit%20Reports): assurance · Security audits and bug-bounty records for the on-chain and compute layers. · `Security Audit Reports`
- [Distribution](https://github.com/morpheusais/docs/blob/HEAD/Smart%20Contracts/Distribution.md): contract · Token distribution and rewards contract documentation. · `Smart Contracts/Distribution.md`
- [L1 Sender](https://github.com/morpheusais/docs/blob/HEAD/Smart%20Contracts/L1Sender.md): bridge contract · Canonical L1-side messaging and transfer initiation. · `Smart Contracts/L1Sender.md`
- [L2 Receiver](https://github.com/morpheusais/docs/blob/HEAD/Smart%20Contracts/L2MessageReceiver.md): bridge contract · L2-side message receipt and processing. · `Smart Contracts/L2MessageReceiver.md`
- [L2 Token Receiver](https://github.com/morpheusais/docs/blob/HEAD/Smart%20Contracts/L2TokenReceiverV2.md): token contract · L2 token-receipt handling for MOR and reward flows. · `Smart Contracts/L2TokenReceiverV2.md`
- [Interval Decrease](https://github.com/morpheusais/docs/blob/HEAD/Smart%20Contracts/LinearDistributionIntervalDecrease.md): reward schedule · Time-based distribution schedule logic. · `Smart Contracts/LinearDistributionIntervalDecrease.md`
- [MOROFT](https://github.com/morpheusais/docs/blob/HEAD/Smart%20Contracts/MOROFT.md): cross-chain token · Cross-chain MOR token contract documentation. · `Smart Contracts/MOROFT.md`

### Operations and support

Guides, FAQs, contribution records, archives, and brand assets.

- [FAQs & Guides](https://github.com/morpheusais/docs/tree/HEAD/!KEYDOCS%20README%20FIRST!/FAQs%20%26%20Guides): user guides · Operational walkthroughs, FAQs, and launch/reward guides. · `!KEYDOCS README FIRST!/FAQs & Guides`
- [Contributions](https://github.com/morpheusais/docs/tree/main/Contributions): proof records · Proof-of-contribution records for code, compute, and community work. · `Contributions`
- [Archive](https://github.com/morpheusais/docs/tree/main/Archive): historical docs · Versioned legacy guides, prior releases, and translated reference material. · `Archive`
- [Graphics](https://github.com/morpheusais/docs/tree/main/Graphics): brand assets · Diagrams, logos, and documentation illustration assets. · `Graphics`
- [Multisig Log](https://github.com/morpheusais/docs/tree/main/MultisigLog): ops log · Historical multisignature activity record. · `MultisigLog`
- [Guide Collections](https://github.com/morpheusais/docs/tree/HEAD/!KEYDOCS%20README%20FIRST!/FAQs%20%26%20Guides/Guides): workflow guides · Mainnet, testnet, staking, bridging, swap, and setup walkthroughs. · `!KEYDOCS README FIRST!/FAQs & Guides/Guides`

## Connections

- README → Fundamentals: frames · README points into the core protocol narrative.
- README → Capital Providers: organizes · README routes readers to capital-provider economics.
- README → Code Providers: organizes · README routes readers to code-provider documentation.
- README → Compute Providers: organizes · README routes readers to compute-provider documentation.
- README → FAQs & Guides: links · README connects to operational guides and FAQs.
- README → Smart Contracts: separates · README distinguishes the on-chain subsystem.
- README → Audit Reports: trusts · README connects the protocol to its assurance layer.
- README → Contributions: records · README links to contribution accounting artifacts.
- Fundamentals → Capital Providers: informs · Protocol fundamentals feed tokenomics and launch mechanics.
- Capital Providers → Distribution: uses · Capital-provider mechanics rely on distribution logic.
- Capital Providers → Interval Decrease: uses · Reward flows depend on interval-based schedules.
- Capital Providers → MOROFT: centers on · Capital docs describe MOR token and launch behavior.
- Smart Contracts → Distribution: includes · Distribution is a core documented contract.
- Smart Contracts → L1 Sender: includes · L1 sender is part of the cross-chain contract set.
- Smart Contracts → L2 Receiver: includes · L2 message receiver is part of the cross-chain contract set.
- Smart Contracts → L2 Token Receiver: includes · L2 token receiver handles L2 token flows.
- Smart Contracts → Interval Decrease: includes · Distribution scheduling is documented as a contract component.
- Smart Contracts → MOROFT: includes · MOROFT represents the cross-chain token contract.
- FAQs & Guides → Guide Collections: contains · The guide collection is the operational entry point.
- Compute Providers → FAQs & Guides: supports · Compute documentation is paired with setup and usage guides.
- Code Providers → Contributions: feeds · Contribution weights and best practices connect to proof-of-contribution records.
- Audit Reports → Smart Contracts: verifies · Audit reports provide assurance for the on-chain subsystem.
- Archive → Fundamentals: preserves · Archived reference material captures earlier protocol docs.
- Graphics → FAQs & Guides: supports · Brand and diagram assets support the guide layer.
- Multisig Log → Capital Providers: tracks · Multisig history relates to capital and treasury operations.
