# shc-labs/dragonsmarket architecture

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

- Interactive diagram: https://gitdiagram.com/shc-labs/dragonsmarket
- Repository: https://github.com/shc-labs/dragonsmarket

## Overview

Dragons Market is a NEAR prediction-market application: users trade event Yes/No shares or short-window Up/Down rounds, then redeem or receive results after resolution. Proposed market results can be challenged and decided by a Dragon-holder jury; platform revenue also supports quarterly holder claims. The website, backend indexer/read API, contracts, and keeper form the core product, with agent access and an MCP interface as additional capabilities. The README documents the product stages; source excerpts establish selected backend and MCP calls, so unsampled runtime links are omitted.

Main entry points: [`contracts/keeper/keeper.mjs`](https://github.com/shc-labs/dragonsmarket/blob/main/contracts/keeper/keeper.mjs) (Keeper workers), [`backend/src/read-api.ts`](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/read-api.ts) (Read API), [`backend/src/ingestion/engine.ts`](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/ingestion/engine.ts) (Chain ingestion), [`contracts/market/src/lib.rs`](https://github.com/shc-labs/dragonsmarket/blob/main/contracts/market/src/lib.rs) (Event markets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["On-chain products"]
  node_market["Event markets<br/>[lib.rs]"]
  node_rounds["Price rounds<br/>[lib.rs]"]
  node_oracle["Results and jury<br/>[lib.rs]"]
  node_council["Dragon Council<br/>[lib.rs]"]
end

subgraph group_backend["Backend services"]
  node_backend["Backend API<br/>[app.ts]"]
  node_auth["Wallet sign-in<br/>[auth.ts]"]
  node_ingest["Chain ingestion<br/>[engine.ts]"]
  node_block["Block preparation<br/>[block.ts]"]
  node_indexstore[("Indexed records<br/>[store.ts]")]
  node_readapi["Read API<br/>[read-api.ts]"]
  node_database[("Postgres<br/>[database.ts]")]
  node_agents["Agent operations<br/>[agent-accounts.ts]"]
  node_agentactions["Agent actions<br/>[agent-actions.ts]"]
  node_agentroutes["Agent routing<br/>[agent-routes.ts]"]
end

subgraph group_interfaces["User interfaces"]
  node_web["Website"]
end

subgraph group_automation["Automation and agents"]
  node_keeper["Keeper workers<br/>[keeper.mjs]"]
  node_mcp["MCP interface<br/>[server.ts]"]
  node_mcptools["MCP tools<br/>[tools.ts]"]
  node_mcpbackend["MCP backend client<br/>[backend.ts]"]
end

node_user(("Market participant"))
node_chain{{"NEAR chain"}}
node_intents{{"NEAR Intents"}}
node_jury(("Dragon holders"))

node_user -->|"uses"| node_web
node_web -.->|"trades shares"| node_market
node_market -->|"executes on"| node_chain
node_rounds -->|"executes on"| node_chain
node_oracle -->|"executes on"| node_chain
node_council -->|"executes on"| node_chain
node_intents -->|"holds collateral"| node_market
node_jury -->|"votes on challenges"| node_oracle
node_keeper -->|"sends transactions"| node_chain
node_keeper -->|"advances finalization"| node_oracle
node_keeper -->|"publishes prices"| node_rounds
node_keeper -->|"sweeps fees"| node_council
node_backend -->|"routes reads"| node_readapi
node_backend -->|"serves sign-in"| node_auth
node_ingest -->|"prepares blocks"| node_block
node_ingest -->|"commits blocks"| node_indexstore
node_readapi -->|"reads index status"| node_indexstore
node_readapi -->|"queries records"| node_database
node_agents -->|"uses actions"| node_agentactions
node_agentroutes -->|"dispatches requests"| node_agents
node_agentroutes -->|"runs actions"| node_agentactions
node_mcp -->|"builds tools"| node_mcptools
node_mcptools -->|"calls backend"| node_mcpbackend
node_ingest -->|"indexes finalized data"| node_chain
node_readapi -->|"serves indexed data"| node_user

click node_web "https://github.com/shc-labs/dragonsmarket/tree/main/web/app"
click node_market "https://github.com/shc-labs/dragonsmarket/blob/main/contracts/market/src/lib.rs"
click node_rounds "https://github.com/shc-labs/dragonsmarket/blob/main/contracts/rounds/src/lib.rs"
click node_oracle "https://github.com/shc-labs/dragonsmarket/blob/main/contracts/oracle/src/lib.rs"
click node_council "https://github.com/shc-labs/dragonsmarket/blob/main/contracts/council/src/lib.rs"
click node_keeper "https://github.com/shc-labs/dragonsmarket/blob/main/contracts/keeper/keeper.mjs"
click node_backend "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/app.ts"
click node_auth "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/auth.ts"
click node_ingest "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/ingestion/engine.ts"
click node_block "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/ingestion/block.ts"
click node_indexstore "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/ingestion/store.ts"
click node_readapi "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/read-api.ts"
click node_database "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/database.ts"
click node_agents "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/agent-accounts.ts"
click node_agentactions "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/agent-actions.ts"
click node_agentroutes "https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/agent-routes.ts"
click node_mcp "https://github.com/shc-labs/dragonsmarket/blob/main/mcp/src/server.ts"
click node_mcptools "https://github.com/shc-labs/dragonsmarket/blob/main/mcp/src/tools.ts"
click node_mcpbackend "https://github.com/shc-labs/dragonsmarket/blob/main/mcp/src/backend.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_market,node_rounds,node_oracle,node_council toneBlue
class node_backend,node_auth,node_ingest,node_block,node_indexstore,node_readapi,node_database,node_agents,node_agentactions,node_agentroutes toneAmber
class node_web toneMint
class node_keeper,node_mcp,node_mcptools,node_mcpbackend toneRose
class node_user,node_chain,node_intents,node_jury toneIndigo
```

## Components

### On-chain products

- [Event markets](https://github.com/shc-labs/dragonsmarket/blob/main/contracts/market/src/lib.rs): `contracts/market/src/lib.rs`
- [Price rounds](https://github.com/shc-labs/dragonsmarket/blob/main/contracts/rounds/src/lib.rs): `contracts/rounds/src/lib.rs`
- [Results and jury](https://github.com/shc-labs/dragonsmarket/blob/main/contracts/oracle/src/lib.rs): `contracts/oracle/src/lib.rs`
- [Dragon Council](https://github.com/shc-labs/dragonsmarket/blob/main/contracts/council/src/lib.rs): `contracts/council/src/lib.rs`

### Backend services

- [Backend API](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Wallet sign-in](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/auth.ts): `backend/src/auth.ts`
- [Chain ingestion](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/ingestion/engine.ts): `backend/src/ingestion/engine.ts`
- [Block preparation](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/ingestion/block.ts): `backend/src/ingestion/block.ts`
- [Indexed records](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/ingestion/store.ts): `backend/src/ingestion/store.ts`
- [Read API](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/read-api.ts): `backend/src/read-api.ts`
- [Postgres](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/database.ts): `backend/src/database.ts`
- [Agent operations](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/agent-accounts.ts): `backend/src/agent-accounts.ts`
- [Agent actions](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/agent-actions.ts): `backend/src/agent-actions.ts`
- [Agent routing](https://github.com/shc-labs/dragonsmarket/blob/main/backend/src/agent-routes.ts): `backend/src/agent-routes.ts`

### User interfaces

- [Website](https://github.com/shc-labs/dragonsmarket/tree/main/web/app): `web/app`

### Automation and agents

- [Keeper workers](https://github.com/shc-labs/dragonsmarket/blob/main/contracts/keeper/keeper.mjs): `contracts/keeper/keeper.mjs`
- [MCP interface](https://github.com/shc-labs/dragonsmarket/blob/main/mcp/src/server.ts): `mcp/src/server.ts`
- [MCP tools](https://github.com/shc-labs/dragonsmarket/blob/main/mcp/src/tools.ts): `mcp/src/tools.ts`
- [MCP backend client](https://github.com/shc-labs/dragonsmarket/blob/main/mcp/src/backend.ts): `mcp/src/backend.ts`

### Other components

- **Market participant**
- **NEAR chain**
- **NEAR Intents**
- **Dragon holders**

## Connections

- Market participant → Website: uses (evidence: `README.md`)
- Website → Event markets: trades shares
- Event markets → NEAR chain: executes on (evidence: `README.md`)
- Price rounds → NEAR chain: executes on (evidence: `README.md`)
- Results and jury → NEAR chain: executes on (evidence: `README.md`)
- Dragon Council → NEAR chain: executes on (evidence: `README.md`)
- NEAR Intents → Event markets: holds collateral (evidence: `README.md`)
- Dragon holders → Results and jury: votes on challenges (evidence: `README.md`)
- Keeper workers → NEAR chain: sends transactions (evidence: `README.md`)
- Keeper workers → Results and jury: advances finalization (evidence: `README.md`)
- Keeper workers → Price rounds: publishes prices (evidence: `README.md`)
- Keeper workers → Dragon Council: sweeps fees (evidence: `README.md`)
- Backend API → Read API: routes reads (evidence: `backend/src/app.ts`)
- Backend API → Wallet sign-in: serves sign-in (evidence: `backend/src/main.ts`)
- Chain ingestion → Block preparation: prepares blocks (evidence: `backend/src/ingestion/engine.ts`)
- Chain ingestion → Indexed records: commits blocks (evidence: `backend/src/ingestion/engine.ts`)
- Read API → Indexed records: reads index status (evidence: `backend/src/read-api.ts`)
- Read API → Postgres: queries records (evidence: `backend/src/read-api.ts`)
- Agent operations → Agent actions: uses actions (evidence: `backend/src/agent-accounts.ts`)
- Agent routing → Agent operations: dispatches requests (evidence: `backend/src/agent-routes.ts`)
- Agent routing → Agent actions: runs actions (evidence: `backend/src/agent-routes.ts`)
- MCP interface → MCP tools: builds tools (evidence: `mcp/src/server.ts`)
- MCP tools → MCP backend client: calls backend (evidence: `mcp/src/tools.ts`)
- Chain ingestion → NEAR chain: indexes finalized data (evidence: `README.md`)
- Read API → Market participant: serves indexed data (evidence: `README.md`)