proxmox/docs/11-references/SUBMODULE_RELATIONSHIP_MAP.md

# Submodule Relationship Map

**Last Updated:** 2026-02-26  
**Status:** 🟢 Active Master Reference  
**Purpose:** Document all submodules and their relationships  
**Source of truth:** Root [.gitmodules](../../.gitmodules) — reconciled 2026-02-26.

---

## Submodule Overview

**Root-level submodules (per .gitmodules):** 17  
**Nested (arromis-monorepo):** 5  
**Total (including nested):** 20  

**Note:** Root README and PROJECT_STRUCTURE also reference `smom-dbis-138-proxmox/` (deployment scripts). That directory may exist as a sibling or legacy clone; the **git submodule** is `smom-dbis-138` (path `smom-dbis-138/`). See [Submodule Issues & Notes](#submodule-issues--notes).

---

## Root-Level Submodules

### Core Infrastructure

| Submodule | Path | Repository | Purpose | Dependencies |
|-----------|------|------------|---------|--------------|
| **mcp-proxmox** | `mcp-proxmox/` | https://github.com/gilby125/mcp-proxmox.git | Proxmox MCP Server | None |
| **ProxmoxVE** | `ProxmoxVE/` | https://github.com/community-scripts/ProxmoxVE.git | Proxmox helper scripts | None |

### Blockchain & DeFi

| Submodule | Path | Repository | Purpose | Dependencies |
|-----------|------|------------|---------|--------------|
| **smom-dbis-138** | `smom-dbis-138/` | git@github.com:Order-of-Hospitallers/smom-dbis-138.git | Blockchain network / services | None |
| **explorer-monorepo** | `explorer-monorepo/` | https://github.com/Order-of-Hospitallers/chain-138-explorer.git | Blockchain explorer | smom-dbis-138 |
| **metamask-integration** | `metamask-integration/` | git@github.com:Defi-Oracle-Meta-Blockchain/metamask-integration.git | MetaMask integration | smom-dbis-138 |
| **fireblocks-integration** | `fireblocks-integration/` | https://gitea.d-bis.org/d-bis/fireblocks-integration.git | Fireblocks Web3 (Chain 138 RPC, docs) | smom-dbis-138 (RPC) |
| **alltra-lifi-settlement** | `alltra-lifi-settlement/` | https://github.com/bis-innovations/LiFi_Pay_Alltra_Integration_Submodule.git | LiFi/Alltra settlement | None |
| **cross-chain-pmm-lps** | `cross-chain-pmm-lps/` | https://gitea.d-bis.org/d-bis/cross-chain-pmm-lps.git | cW* M1 public-chain single-sided PMM stabilization mesh (bot, pool topology, peg bands, oracles) | smom-dbis-138 / token-mapping (reference) |
| **ai-mcp-pmm-controller** | `ai-mcp-pmm-controller/` | https://gitea.d-bis.org/d-bis/ai-mcp-pmm-controller.git | 5701 MCP hub for DODO PMM (read-only + risk scoring, pool allowlist, policy gate) | See [AI_AGENTS_57XX_DEPLOYMENT_PLAN.md](../02-architecture/AI_AGENTS_57XX_DEPLOYMENT_PLAN.md) Appendix F |
| **OMNIS** | `OMNIS/` | https://github.com/Defi-Oracle-Tooling/OMNIS.git | OMNIS platform | None |

### Business Systems

| Submodule | Path | Repository | Purpose | Dependencies |
|-----------|------|------------|---------|--------------|
| **dbis_core** | `dbis_core/` | git@github.com:Order-of-Hospitallers/dbis_core.git | DBIS Core banking | PostgreSQL, Redis |
| **the-order** | `the-order/` | git@github.com:Order-of-Hospitallers/the-order-monorepo.git | Order management | dbis_core (optional) |
| **miracles_in_motion** | `miracles_in_motion/` | https://github.com/Order-of-Hospitallers/miracles_in_motion.git | MIM4U platform | None |
| **metaverseDubai** | `metaverseDubai/` | https://github.com/Order-of-Hospitallers/metaverseDubai.git | Metaverse project | None |

### Documentation & Tools

| Submodule | Path | Repository | Purpose | Dependencies |
|-----------|------|------------|---------|--------------|
| **gru-docs** | `gru-docs/` | https://github.com/Defi-Oracle-Tooling/GRU-Official-Docs-Monetary-Policies.git | GRU documentation (monetary policy, Diamond/contracts, compliance) | None. Same repo is often cloned standalone as **GRU-Official-Docs-Monetary-Policies** (e.g. `~/projects/GRU-Official-Docs-Monetary-Policies`). |

### ARROMIS Organization

| Submodule | Path | Repository | Purpose | Dependencies |
|-----------|------|------------|---------|--------------|
| **arromis-monorepo** | `arromis-monorepo/` | https://github.com/ARROMIS/arromis-monorepo.git | ARROMIS monorepo | Contains 5 submodules |
| **omada-api** | `omada-api/` | https://github.com/ARROMIS/omada-api.git | Omada API client | ⚠️ Workspace package (may not be proper submodule) |

### PR Workspace

| Submodule | Path | Repository | Purpose | Dependencies |
|-----------|------|------------|---------|--------------|
| **pr-workspace/app-ethereum** | `pr-workspace/app-ethereum/` | https://github.com/defiQUG/app-ethereum.git | Ethereum app | None |
| **pr-workspace/chains** | `pr-workspace/chains/` | https://github.com/defiQUG/chains.git | Chain data | None |

---

## Nested Submodules (arromis-monorepo)

| Submodule | Path | Repository | Purpose |
|-----------|------|------------|---------|
| **arromis-documentation** | `arromis-monorepo/arromis-documentation/` | https://github.com/ARROMIS/arromis-documentation.git | Documentation |
| **arromis-coordination-hub** | `arromis-monorepo/arromis-coordination-hub/` | https://github.com/ARROMIS/arromis-coordination-hub.git | Coordination hub |
| **sovereign-body-registry** | `arromis-monorepo/sovereign-body-registry/` | https://github.com/ARROMIS/sovereign-body-registry.git | Registry service |
| **deployment-orchestrator** | `arromis-monorepo/deployment-orchestrator/` | https://github.com/ARROMIS/deployment-orchestrator.git | Deployment automation |
| **integration-templates** | `arromis-monorepo/integration-templates/` | https://github.com/ARROMIS/integration-templates.git | Integration templates |

---

## Submodule Relationships

### Dependency Graph

```
proxmox (root)
├── mcp-proxmox (standalone)
├── ProxmoxVE (standalone)
├── smom-dbis-138 (standalone)     ← .gitmodules path (smom-dbis-138-proxmox/ may exist separately)
│   ├── explorer-monorepo (depends on: smom-dbis-138)
│   ├── metamask-integration (depends on: smom-dbis-138)
│   └── fireblocks-integration (depends on: smom-dbis-138 RPC)
├── alltra-lifi-settlement (standalone)
├── cross-chain-pmm-lps (standalone)
├── dbis_core (standalone)
│   └── the-order (optional dependency: dbis_core)
├── OMNIS (standalone)
├── miracles_in_motion (standalone)
├── metaverseDubai (standalone)
├── gru-docs (standalone)
├── arromis-monorepo (standalone)
│   ├── arromis-documentation
│   ├── arromis-coordination-hub
│   ├── sovereign-body-registry
│   ├── deployment-orchestrator
│   └── integration-templates
├── omada-api (⚠️ workspace package, may not be proper submodule)
└── pr-workspace/
    ├── app-ethereum (standalone)
    └── chains (standalone)
```

---

## Submodule Issues & Notes

### Issues

1. **smom-dbis-138 vs smom-dbis-138-proxmox**
   - **.gitmodules** has only `smom-dbis-138` (path `smom-dbis-138/`). Root README and PROJECT_STRUCTURE refer to **smom-dbis-138-proxmox** for "deployment scripts." If both directories exist, treat `smom-dbis-138` as the git submodule (blockchain/services) and `smom-dbis-138-proxmox` as deployment-specific content or legacy path; docs/README links to `smom-dbis-138-proxmox/README.md` for deployment docs.

2. **omada-api**
   - **Issue:** Marked as workspace package but tracked as submodule
   - **Impact:** May not be proper submodule
   - **Recommendation:** Verify if repository exists, otherwise convert to workspace package

### Notes

- **cross-chain-pmm-lps:** cW* M1 public-chain PMM stabilization mesh; repo: https://gitea.d-bis.org/d-bis/cross-chain-pmm-lps.git
- **explorer-monorepo:** URL in .gitmodules is `https://github.com/Order-of-Hospitallers/chain-138-explorer.git` (fixed; was previously documented as local path).
- **arromis-monorepo:** Contains 5 nested submodules (migrated from root ARROMIS/ directory).
- **pr-workspace:** Contains 2 submodules for PR workspace functionality.
- **Total nested depth:** 2 levels (root → arromis-monorepo → submodules).

---

## Submodule Update Procedures

### Update All Submodules
```bash
git submodule update --init --recursive
git submodule update --remote
```

### Update Specific Submodule
```bash
cd <submodule-path>
git pull origin main
cd ..
git add <submodule-path>
git commit -m "Update <submodule-name>"
```

### Update Nested Submodules (arromis-monorepo)
```bash
cd arromis-monorepo
git submodule update --init --recursive
git submodule update --remote
cd ..
git add arromis-monorepo
git commit -m "Update arromis-monorepo submodules"
```

---

## Version Compatibility

### Current Versions
- All submodules pinned to specific commits
- Check `.gitmodules` for current commit references
- Use `git submodule status` to see current versions

### Compatibility Matrix
- **smom-dbis-138** ↔ **explorer-monorepo**: Compatible
- **smom-dbis-138** ↔ **metamask-integration**: Compatible
- **dbis_core** ↔ **the-order**: Optional dependency

---

## Related Documents

- **[.gitmodules](../../.gitmodules)** - Git submodule configuration (repo root)
- **[PROJECT_STRUCTURE.md](../../PROJECT_STRUCTURE.md)** - Project and directory structure
- **[COMPREHENSIVE_PROJECT_REVIEW.md](../archive/00-meta-pruned/COMPREHENSIVE_PROJECT_REVIEW.md)** - Project review

---

**Last Updated:** 2026-02-26  
**Maintainer:** System Administrator  
**Update Frequency:** On submodule additions/removals  
**Current Status:** ✅ Reconciled with .gitmodules (16 root + 5 nested); cross-chain-pmm-lps submodule (Gitea) added; explorer URL and alltra-lifi-settlement added; smom-dbis-138 vs -proxmox noted.