# yaminyann/dex-on-arc architecture

> Architecture diagram of the GitHub repository yaminyann/dex-on-arc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yaminyann/dex-on-arc
- Repository: https://github.com/yaminyann/dex-on-arc

## Overview

Lumarc is a non-custodial Arc trading terminal. A wallet user enters the app, chooses a trading capability, and signs transactions through their wallet; orders escrow funds in the contract and execute only when a keeper submits them. The graph also preserves the documented portfolio, dashboard, agent, administration, and testnet-harness capabilities. The source excerpts show app routing and backend startup, but not every component’s calls, so undocumented links are omitted.

Main entry points: [`src/trading/ordersAbi.ts`](https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/ordersAbi.ts) (Orders contract), [`src/App.tsx`](https://github.com/yaminyann/dex-on-arc/blob/main/src/App.tsx) (App shell), [`src/trading/agent/engine.ts`](https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/agent/engine.ts) (Command execution), [`server/index.ts`](https://github.com/yaminyann/dex-on-arc/blob/main/server/index.ts) (Backend API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Trading interface"]
  node_app["App shell<br/>[App.tsx]"]
  node_terminal["Trading terminal<br/>[Terminal.tsx]"]
  node_dashboard["Portfolio dashboard<br/>[Dashboard.tsx]"]
  node_admin["Owner administration<br/>[Admin.tsx]"]
  node_settings["App settings<br/>[SettingsPage.tsx]"]
  node_trade_panel["Market and order forms<br/>[TradePanel.tsx]"]
  node_order_views["Order tables and tabs<br/>[OrderTables.tsx]"]
end

subgraph group_trading["Trading services"]
  node_trading_hooks["Chain data hooks<br/>[hooks.ts]"]
  node_aggregator["Swap aggregator client<br/>[aggregator.ts]"]
  node_network_config["Network configuration<br/>[networks.ts]"]
  node_onchain_facts["Chain facts<br/>[onchain-facts.ts]"]
end

subgraph group_agent["Agent Station"]
  node_agent_station["Agent Station<br/>[AgentStation.tsx]"]
  node_agent_parser["Command parser<br/>[parser.ts]"]
  node_agent_engine["Command execution<br/>[engine.ts]"]
  node_agent_permissions["Agent permissions"]
end

subgraph group_backend["Backend services"]
  node_api["Backend API<br/>[index.ts]"]
  node_gateway["Quote gateway<br/>[instance.ts]"]
  node_keeper["Order keeper<br/>[keeper.ts]"]
  node_indexer["Order event indexer<br/>[runtime.ts]"]
  node_index_db[("Indexer database<br/>[db.ts]")]
end

subgraph group_chain["On-chain execution"]
  node_orders_contract["Orders contract<br/>[ordersAbi.ts]"]
end

node_user(("Wallet user"))
node_wallet(("Connected wallet"))
node_arc_chain{{"Arc network"}}
node_quote_providers{{"Quote providers"}}

node_user -->|"opens"| node_app
node_app -->|"routes to"| node_terminal
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_agent_station
node_app -->|"routes to"| node_admin
node_app -->|"routes to"| node_settings
node_terminal -->|"offers trading"| node_trade_panel
node_terminal -->|"shows orders"| node_order_views
node_user -->|"connects"| node_wallet
node_trade_panel -.->|"requests signatures"| node_wallet
node_trade_panel -.->|"creates orders"| node_orders_contract
node_dashboard -.->|"reads portfolio"| node_orders_contract
node_admin -.->|"manages settings"| node_orders_contract
node_agent_station -->|"parses commands"| node_agent_parser
node_agent_station -.->|"executes plans"| node_agent_engine
node_agent_engine -->|"checks limits"| node_agent_permissions
node_agent_engine -->|"reads oracle"| node_trading_hooks
node_agent_engine -.->|"submits orders"| node_orders_contract
node_trading_hooks -->|"reads contract"| node_orders_contract
node_trading_hooks -->|"fetches health"| node_aggregator
node_network_config -->|"loads chain facts"| node_onchain_facts
node_api -->|"configures gateway"| node_gateway
node_api -->|"starts keeper"| node_keeper
node_api -->|"starts indexer"| node_indexer
node_keeper -->|"ranks quotes"| node_gateway
node_keeper -->|"executes orders"| node_orders_contract
node_indexer -->|"stores indexed data"| node_index_db
node_indexer -->|"reads event logs"| node_orders_contract
node_gateway -.->|"requests quotes"| node_quote_providers
node_wallet -.->|"signs transactions"| node_arc_chain
node_orders_contract -->|"escrows funds"| node_arc_chain

click node_app "https://github.com/yaminyann/dex-on-arc/blob/main/src/App.tsx"
click node_terminal "https://github.com/yaminyann/dex-on-arc/blob/main/src/components/Terminal.tsx"
click node_dashboard "https://github.com/yaminyann/dex-on-arc/blob/main/src/components/Dashboard.tsx"
click node_admin "https://github.com/yaminyann/dex-on-arc/blob/main/src/components/Admin.tsx"
click node_settings "https://github.com/yaminyann/dex-on-arc/blob/main/src/components/SettingsPage.tsx"
click node_trade_panel "https://github.com/yaminyann/dex-on-arc/blob/main/src/components/TradePanel.tsx"
click node_order_views "https://github.com/yaminyann/dex-on-arc/blob/main/src/components/OrderTables.tsx"
click node_agent_station "https://github.com/yaminyann/dex-on-arc/blob/main/src/components/AgentStation.tsx"
click node_agent_parser "https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/agent/parser.ts"
click node_agent_engine "https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/agent/engine.ts"
click node_agent_permissions "https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/agent-permission.ts"
click node_trading_hooks "https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/hooks.ts"
click node_aggregator "https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/aggregator.ts"
click node_network_config "https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/networks.ts"
click node_onchain_facts "https://github.com/yaminyann/dex-on-arc/blob/main/src/onchain-facts.ts"
click node_api "https://github.com/yaminyann/dex-on-arc/blob/main/server/index.ts"
click node_gateway "https://github.com/yaminyann/dex-on-arc/blob/main/server/gateway/instance.ts"
click node_keeper "https://github.com/yaminyann/dex-on-arc/blob/main/server/keeper.ts"
click node_indexer "https://github.com/yaminyann/dex-on-arc/blob/main/server/indexer/runtime.ts"
click node_index_db "https://github.com/yaminyann/dex-on-arc/blob/main/server/indexer/db.ts"
click node_orders_contract "https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/ordersAbi.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_app,node_terminal,node_dashboard,node_admin,node_settings,node_trade_panel,node_order_views,node_user toneBlue
class node_trading_hooks,node_aggregator,node_network_config,node_onchain_facts toneAmber
class node_agent_station,node_agent_parser,node_agent_engine,node_agent_permissions toneMint
class node_api,node_gateway,node_keeper,node_indexer,node_index_db toneRose
class node_orders_contract,node_wallet,node_arc_chain,node_quote_providers toneIndigo
```

## Components

### Trading interface

- [App shell](https://github.com/yaminyann/dex-on-arc/blob/main/src/App.tsx): `src/App.tsx`
- [Trading terminal](https://github.com/yaminyann/dex-on-arc/blob/main/src/components/Terminal.tsx): `src/components/Terminal.tsx`
- [Portfolio dashboard](https://github.com/yaminyann/dex-on-arc/blob/main/src/components/Dashboard.tsx): `src/components/Dashboard.tsx`
- [Owner administration](https://github.com/yaminyann/dex-on-arc/blob/main/src/components/Admin.tsx): `src/components/Admin.tsx`
- [App settings](https://github.com/yaminyann/dex-on-arc/blob/main/src/components/SettingsPage.tsx): `src/components/SettingsPage.tsx`
- [Market and order forms](https://github.com/yaminyann/dex-on-arc/blob/main/src/components/TradePanel.tsx): `src/components/TradePanel.tsx`
- [Order tables and tabs](https://github.com/yaminyann/dex-on-arc/blob/main/src/components/OrderTables.tsx): `src/components/OrderTables.tsx`

### Trading services

- [Chain data hooks](https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/hooks.ts): `src/trading/hooks.ts`
- [Swap aggregator client](https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/aggregator.ts): `src/trading/aggregator.ts`
- [Network configuration](https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/networks.ts): `src/trading/networks.ts`
- [Chain facts](https://github.com/yaminyann/dex-on-arc/blob/main/src/onchain-facts.ts): `src/onchain-facts.ts`

### Agent Station

- [Agent Station](https://github.com/yaminyann/dex-on-arc/blob/main/src/components/AgentStation.tsx): `src/components/AgentStation.tsx`
- [Command parser](https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/agent/parser.ts): `src/trading/agent/parser.ts`
- [Command execution](https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/agent/engine.ts): `src/trading/agent/engine.ts`
- [Agent permissions](https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/agent-permission.ts): `src/trading/agent-permission.ts`

### Backend services

- [Backend API](https://github.com/yaminyann/dex-on-arc/blob/main/server/index.ts): `server/index.ts`
- [Quote gateway](https://github.com/yaminyann/dex-on-arc/blob/main/server/gateway/instance.ts): `server/gateway/instance.ts`
- [Order keeper](https://github.com/yaminyann/dex-on-arc/blob/main/server/keeper.ts): `server/keeper.ts`
- [Order event indexer](https://github.com/yaminyann/dex-on-arc/blob/main/server/indexer/runtime.ts): `server/indexer/runtime.ts`
- [Indexer database](https://github.com/yaminyann/dex-on-arc/blob/main/server/indexer/db.ts): `server/indexer/db.ts`

### On-chain execution

- [Orders contract](https://github.com/yaminyann/dex-on-arc/blob/main/src/trading/ordersAbi.ts): `src/trading/ordersAbi.ts`

### Other components

- **Wallet user**
- **Connected wallet**
- **Arc network**
- **Quote providers**

## Connections

- Wallet user → App shell: opens (evidence: `README.md`)
- App shell → Trading terminal: routes to (evidence: `src/App.tsx`)
- App shell → Portfolio dashboard: routes to (evidence: `src/App.tsx`)
- App shell → Agent Station: routes to (evidence: `src/App.tsx`)
- App shell → Owner administration: routes to (evidence: `src/App.tsx`)
- App shell → App settings: routes to (evidence: `src/App.tsx`)
- Trading terminal → Market and order forms: offers trading (evidence: `README.md`)
- Trading terminal → Order tables and tabs: shows orders (evidence: `README.md`)
- Wallet user → Connected wallet: connects (evidence: `README.md`)
- Market and order forms → Connected wallet: requests signatures
- Market and order forms → Orders contract: creates orders (evidence: `README.md`)
- Portfolio dashboard → Orders contract: reads portfolio (evidence: `README.md`)
- Owner administration → Orders contract: manages settings (evidence: `README.md`)
- Agent Station → Command parser: parses commands (evidence: `src/components/AgentStation.tsx`)
- Agent Station → Command execution: executes plans (evidence: `src/components/AgentStation.tsx`)
- Command execution → Agent permissions: checks limits (evidence: `src/trading/agent/engine.ts`)
- Command execution → Chain data hooks: reads oracle (evidence: `src/trading/agent/engine.ts`)
- Command execution → Orders contract: submits orders (evidence: `src/trading/agent/engine.ts`)
- Chain data hooks → Orders contract: reads contract (evidence: `src/trading/hooks.ts`)
- Chain data hooks → Swap aggregator client: fetches health (evidence: `src/trading/hooks.ts`)
- Network configuration → Chain facts: loads chain facts (evidence: `src/trading/networks.ts`)
- Backend API → Quote gateway: configures gateway (evidence: `server/index.ts`)
- Backend API → Order keeper: starts keeper (evidence: `server/index.ts`)
- Backend API → Order event indexer: starts indexer (evidence: `server/index.ts`)
- Order keeper → Quote gateway: ranks quotes (evidence: `server/keeper.ts`)
- Order keeper → Orders contract: executes orders (evidence: `server/keeper.ts`)
- Order event indexer → Indexer database: stores indexed data (evidence: `server/indexer/runtime.ts`)
- Order event indexer → Orders contract: reads event logs (evidence: `server/indexer/runtime.ts`)
- Quote gateway → Quote providers: requests quotes
- Connected wallet → Arc network: signs transactions (evidence: `README.md`)
- Orders contract → Arc network: escrows funds (evidence: `README.md`)