# ship-armada/armada-poc architecture

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

- Interactive diagram: https://gitdiagram.com/ship-armada/armada-poc
- Repository: https://github.com/ship-armada/armada-poc

## Overview

Armada combines near-term crowdfund and governance applications with a local cross-chain privacy-pool and shielded-yield demo. Participants use the crowdfund app to commit and claim; governance users inspect and manage proposals and treasury state. In the demo, users shield, privately transfer, unshield, or use yield, while the relayer supports cross-chain operations. The repository tree omits the Solidity contracts, and several key flows are documented but their implementation was not sampled; dashed edges mark those unverified connections.

Main entry points: [`governance-ui/src/App.tsx`](https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/App.tsx) (Governance App), [`lib/sdk/index.ts`](https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/index.ts) (Privacy SDK), [`relayer/armada-relayer.ts`](https://github.com/ship-armada/armada-poc/blob/main/relayer/armada-relayer.ts) (Armada Relayer), [`mcp-server/src/server.ts`](https://github.com/ship-armada/armada-poc/blob/main/mcp-server/src/server.ts) (MCP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_crowdfund["Crowdfund"]
  node_committer["Committer App<br/>[App.tsx]"]
  node_commit_pipeline["Commit Pipeline<br/>[useTxPipeline.ts]"]
  node_crowdfund_admin["Admin App<br/>[App.tsx]"]
  node_crowdfund_indexer["Crowdfund Indexer<br/>[server.ts]"]
end

subgraph group_governance["Governance"]
  node_governance_app["Governance App<br/>[App.tsx]"]
  node_wallet["Wallet Access<br/>[useWallet.ts]"]
  node_contract_access["Contract Access"]
  node_governance_data["Governance Data"]
  node_proposals["Proposal Actions<br/>[ProposalsPanel.tsx]"]
  node_proposal_form["Proposal Form"]
  node_treasury["Treasury Controls<br/>[TreasuryPanel.tsx]"]
  node_wind_down["Wind-down Controls<br/>[WindDownPanel.tsx]"]
end

subgraph group_privacy["Privacy Demo"]
  node_sdk["Privacy SDK<br/>[index.ts]"]
  node_sdk_wallet["SDK Wallet<br/>[wallet.ts]"]
  node_sdk_shield["Shield Operations<br/>[shield.ts]"]
  node_sdk_network["Network Scanning<br/>[network.ts]"]
  node_sdk_prover["Proof Builder<br/>[prover.ts]"]
  node_sdk_transfer["Transfer Operations<br/>[transfer.ts]"]
  node_yield_demo["Shielded Yield"]
end

subgraph group_operations["Operations"]
  node_relayer["Armada Relayer<br/>[armada-relayer.ts]"]
  node_wallet_manager["Relayer Wallet<br/>[wallet-manager.ts]"]
  node_network_config["Chain Configuration<br/>[networks.ts]"]
  node_mcp_server["MCP Server<br/>[server.ts]"]
  node_contract_state["Contract Queries<br/>[contract-state.ts]"]
end

node_participant(("Participant"))
node_governance_user(("Governance User"))
node_privacy_user(("Demo User"))

node_participant -.->|"uses"| node_committer
node_committer -.->|"runs pipeline"| node_commit_pipeline
node_participant -.->|"administers sale"| node_crowdfund_admin
node_governance_user -.->|"uses"| node_governance_app
node_governance_app -->|"connects wallet"| node_wallet
node_governance_app -->|"loads contracts"| node_contract_access
node_governance_app -->|"loads data"| node_governance_data
node_governance_data -->|"reads contracts"| node_contract_access
node_governance_app -->|"renders"| node_proposals
node_governance_app -->|"renders"| node_treasury
node_proposals -->|"renders"| node_proposal_form
node_governance_app -.->|"renders"| node_wind_down
node_privacy_user -.->|"requests privacy flows"| node_sdk
node_sdk -->|"exports wallet tools"| node_sdk_wallet
node_sdk -->|"exports shield tools"| node_sdk_shield
node_sdk -->|"exports network tools"| node_sdk_network
node_sdk -->|"exports proof tools"| node_sdk_prover
node_sdk -->|"exports transfer tools"| node_sdk_transfer
node_privacy_user -.->|"uses yield"| node_yield_demo
node_sdk -.->|"supports yield flows"| node_yield_demo
node_relayer -.->|"submits transactions"| node_wallet_manager
node_mcp_server -->|"routes queries"| node_contract_state
node_mcp_server -->|"loads chain roles"| node_network_config
node_relayer -.->|"uses chain topology"| node_network_config

click node_committer "https://github.com/ship-armada/armada-poc/blob/main/crowdfund-ui/packages/committer/src/App.tsx"
click node_commit_pipeline "https://github.com/ship-armada/armada-poc/blob/main/crowdfund-ui/packages/committer/src/hooks/useTxPipeline.ts"
click node_crowdfund_admin "https://github.com/ship-armada/armada-poc/blob/main/crowdfund-ui/packages/admin/src/App.tsx"
click node_crowdfund_indexer "https://github.com/ship-armada/armada-poc/blob/main/crowdfund-ui/packages/indexer/src/api/server.ts"
click node_governance_app "https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/App.tsx"
click node_wallet "https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/hooks/useWallet.ts"
click node_contract_access "https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/hooks/useGovernanceContracts.ts"
click node_governance_data "https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/hooks/useGovernanceData.ts"
click node_proposals "https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/components/ProposalsPanel.tsx"
click node_proposal_form "https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/components/CreateProposalForm.tsx"
click node_treasury "https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/components/TreasuryPanel.tsx"
click node_wind_down "https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/components/WindDownPanel.tsx"
click node_sdk "https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/index.ts"
click node_sdk_wallet "https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/wallet.ts"
click node_sdk_shield "https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/shield.ts"
click node_sdk_network "https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/network.ts"
click node_sdk_prover "https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/prover.ts"
click node_sdk_transfer "https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/transfer.ts"
click node_relayer "https://github.com/ship-armada/armada-poc/blob/main/relayer/armada-relayer.ts"
click node_wallet_manager "https://github.com/ship-armada/armada-poc/blob/main/relayer/modules/wallet-manager.ts"
click node_network_config "https://github.com/ship-armada/armada-poc/blob/main/config/networks.ts"
click node_mcp_server "https://github.com/ship-armada/armada-poc/blob/main/mcp-server/src/server.ts"
click node_contract_state "https://github.com/ship-armada/armada-poc/blob/main/mcp-server/src/tools/contract-state.ts"

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_committer,node_commit_pipeline,node_crowdfund_admin,node_crowdfund_indexer,node_governance_user,node_privacy_user toneBlue
class node_governance_app,node_wallet,node_contract_access,node_governance_data,node_proposals,node_proposal_form,node_treasury,node_wind_down toneAmber
class node_sdk,node_sdk_wallet,node_sdk_shield,node_sdk_network,node_sdk_prover,node_sdk_transfer,node_yield_demo toneMint
class node_relayer,node_wallet_manager,node_network_config,node_mcp_server,node_contract_state toneRose
class node_participant toneIndigo
```

## Components

### Crowdfund

- [Committer App](https://github.com/ship-armada/armada-poc/blob/main/crowdfund-ui/packages/committer/src/App.tsx): `crowdfund-ui/packages/committer/src/App.tsx`
- [Commit Pipeline](https://github.com/ship-armada/armada-poc/blob/main/crowdfund-ui/packages/committer/src/hooks/useTxPipeline.ts): `crowdfund-ui/packages/committer/src/hooks/useTxPipeline.ts`
- [Admin App](https://github.com/ship-armada/armada-poc/blob/main/crowdfund-ui/packages/admin/src/App.tsx): `crowdfund-ui/packages/admin/src/App.tsx`
- [Crowdfund Indexer](https://github.com/ship-armada/armada-poc/blob/main/crowdfund-ui/packages/indexer/src/api/server.ts): `crowdfund-ui/packages/indexer/src/api/server.ts`

### Governance

- [Governance App](https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/App.tsx): `governance-ui/src/App.tsx`
- [Wallet Access](https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/hooks/useWallet.ts): `governance-ui/src/hooks/useWallet.ts`
- [Contract Access](https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/hooks/useGovernanceContracts.ts): `governance-ui/src/hooks/useGovernanceContracts.ts`
- [Governance Data](https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/hooks/useGovernanceData.ts): `governance-ui/src/hooks/useGovernanceData.ts`
- [Proposal Actions](https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/components/ProposalsPanel.tsx): `governance-ui/src/components/ProposalsPanel.tsx`
- [Proposal Form](https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/components/CreateProposalForm.tsx): `governance-ui/src/components/CreateProposalForm.tsx`
- [Treasury Controls](https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/components/TreasuryPanel.tsx): `governance-ui/src/components/TreasuryPanel.tsx`
- [Wind-down Controls](https://github.com/ship-armada/armada-poc/blob/main/governance-ui/src/components/WindDownPanel.tsx): `governance-ui/src/components/WindDownPanel.tsx`

### Privacy Demo

- [Privacy SDK](https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/index.ts): `lib/sdk/index.ts`
- [SDK Wallet](https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/wallet.ts): `lib/sdk/wallet.ts`
- [Shield Operations](https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/shield.ts): `lib/sdk/shield.ts`
- [Network Scanning](https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/network.ts): `lib/sdk/network.ts`
- [Proof Builder](https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/prover.ts): `lib/sdk/prover.ts`
- [Transfer Operations](https://github.com/ship-armada/armada-poc/blob/main/lib/sdk/transfer.ts): `lib/sdk/transfer.ts`
- **Shielded Yield**

### Operations

- [Armada Relayer](https://github.com/ship-armada/armada-poc/blob/main/relayer/armada-relayer.ts): `relayer/armada-relayer.ts`
- [Relayer Wallet](https://github.com/ship-armada/armada-poc/blob/main/relayer/modules/wallet-manager.ts): `relayer/modules/wallet-manager.ts`
- [Chain Configuration](https://github.com/ship-armada/armada-poc/blob/main/config/networks.ts): `config/networks.ts`
- [MCP Server](https://github.com/ship-armada/armada-poc/blob/main/mcp-server/src/server.ts): `mcp-server/src/server.ts`
- [Contract Queries](https://github.com/ship-armada/armada-poc/blob/main/mcp-server/src/tools/contract-state.ts): `mcp-server/src/tools/contract-state.ts`

### Other components

- **Participant**
- **Governance User**
- **Demo User**

## Connections

- Participant → Committer App: uses (evidence: `README.md`)
- Committer App → Commit Pipeline: runs pipeline
- Participant → Admin App: administers sale (evidence: `README.md`)
- Governance User → Governance App: uses (evidence: `README.md`)
- Governance App → Wallet Access: connects wallet (evidence: `governance-ui/src/App.tsx`)
- Governance App → Contract Access: loads contracts (evidence: `governance-ui/src/App.tsx`)
- Governance App → Governance Data: loads data (evidence: `governance-ui/src/App.tsx`)
- Governance Data → Contract Access: reads contracts (evidence: `governance-ui/src/hooks/useGovernanceData.ts`)
- Governance App → Proposal Actions: renders (evidence: `governance-ui/src/App.tsx`)
- Governance App → Treasury Controls: renders (evidence: `governance-ui/src/App.tsx`)
- Proposal Actions → Proposal Form: renders (evidence: `governance-ui/src/components/ProposalsPanel.tsx`)
- Governance App → Wind-down Controls: renders
- Demo User → Privacy SDK: requests privacy flows (evidence: `README.md`)
- Privacy SDK → SDK Wallet: exports wallet tools (evidence: `lib/sdk/index.ts`)
- Privacy SDK → Shield Operations: exports shield tools (evidence: `lib/sdk/index.ts`)
- Privacy SDK → Network Scanning: exports network tools (evidence: `lib/sdk/index.ts`)
- Privacy SDK → Proof Builder: exports proof tools (evidence: `lib/sdk/index.ts`)
- Privacy SDK → Transfer Operations: exports transfer tools (evidence: `lib/sdk/index.ts`)
- Demo User → Shielded Yield: uses yield (evidence: `README.md`)
- Privacy SDK → Shielded Yield: supports yield flows (evidence: `README.md`)
- Armada Relayer → Relayer Wallet: submits transactions
- MCP Server → Contract Queries: routes queries (evidence: `mcp-server/src/server.ts`)
- MCP Server → Chain Configuration: loads chain roles (evidence: `mcp-server/src/server.ts`)
- Armada Relayer → Chain Configuration: uses chain topology
