# decred/dcrdex architecture

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

- Interactive diagram: https://gitdiagram.com/decred/dcrdex
- Repository: https://github.com/decred/dcrdex

## Overview

##### Project’s Main Components
- Client Applications:
- The “client” directory houses Bison Wallet (both desktop “bisonw” and additional client commands) along with modules for trading logic and asset-specific implementations.
- The “companionapp” folder includes an Android application that provides a mobile front-end.
- Webserver components (e.g. “client/webserver” and “client/websocket”) indicate a browser-based interface or additional API layers.
- Server:
- The “server” directory contains the DEX server components including matching, order book management, swap settlement, and order processing.
- API endpoints, admin functions, authentication, and database access layers are clearly organized under “server/auth”, “server/book”, “server/asset”, “server/db” and others.
- Protocol and Core Exchange Logic:
- The “dex” directory holds the protocol code, atomic swap logic, and supporting tests to implement the DEX messaging and matching protocols (including detailed testing and specification support).
- P2P/Decentralized Mesh Component:
- The “tatanka” directory includes the Tatanka Mesh code which is designed to replace the centralized order book model with a decentralized peer-to-peer alternative.
- Additional Infrastructure:
- “internal”, “docs”, and “spec” directories provide internal utilities, developer documentation, and the official specification which underscores the protocol design.
- There are also configuration and deployment files (e.g. Dockerfiles, GitHub workflows, build scripts) which are important when considering how components are built and deployed.

##### Relationships and Interactions
- How the front-end clients (Bison Wallet desktop, web client components, Android companion app) interact with the DEX server over defined API and RPC channels.
- That the server uses modules in “server/asset” for asset-specific operations (atomic swaps, SPV, coin selection, etc.) that integrate with blockchain networks.
- Exchange “dex” module which formalizes the protocols and handles the message flow for order matching.
- Connections from the server to external blockchain nodes (on-chain settlement) as well as interactions with databases (both the bolt DB in “client/db/bolt” and the PostgreSQL-based driver in “server/db”).
- For Tatanka Mesh, illustrate a peer-to-peer network where nodes collectively manage order routing, reputation, and oracle services.

##### Architectural Patterns and Design Principles
- The system separates concerns very well – presentation (client UI and web layers), application logic (DEX matching, order book handling), asset modules (atomic swap, blockchain connectors), and infrastructure (database, network communication).
- The architecture also emphasizes a client–server division (with additional decentralized P2P mesh in Tatanka) and follows micro-modular design to cope with cross-chain atomic swaps.
- Representing error-handling, testing harnesses, and simulation (e.g. “simnet-trade-tests” and “localetest”) as supportive elements for robustness.

##### Relevant Technologies, Frameworks, and Libraries
- Golang is the primary programming language, indicated by the go.mod and .go files.
- Docker containers are used for deployment or testing, as indicated by Dockerfiles and related workflows.
- Additional build and test scripts are included (see GitHub workflows under “.github/workflows”).
- The web interface (built with JavaScript/TypeScript, Node, webpack, etc.) is located in “client/webserver/site”.
- For Android development in the companion app, see the Gradle files and AndroidManifest.xml in the “companionapp/android” folder.
- The system leverages atomic swap protocols, SPV (Simplified Payment Verification) techniques, and decentralized reputation/oracle mechanisms.

##### General Advice
- Be very detailed: include all essential components and microservices.
- Do not shy away from showing sub-components such as asset modules, orderbook subsystems, or even test harnesses if they impact the overall architecture.
- Use clear annotations to indicate the technology stacks (e.g. “Golang”, “Docker”, “Webpack/JS”) and architectural motifs (e.g. client–server, microservices, P2P overlay).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Applications
    subgraph "Client Applications"
        A1["Bison Wallet Desktop"]:::client
        A2["Trading Logic & Asset Modules"]:::client
        A3["Web Client Components"]:::client
        A4["Android Companion App"]:::client
    end

    %% DEX Server Components
    subgraph "DEX Server"
        B1["DEX Server Core"]:::server
        B2["API & Auth"]:::server
        B3["Database Access Layer"]:::server
        B4["Asset Services"]:::server
    end

    %% Protocol and Core Exchange Logic
    subgraph "Protocol & Core Exchange Logic"
        C1["DEX Protocol"]:::protocol
    end

    %% P2P/Decentralized Mesh Component
    subgraph "Tatanka Mesh Network"
        D1["Tatanka Mesh"]:::p2p
    end

    %% External Systems
    E1["Blockchain Networks"]:::ext

    %% Additional Infrastructure
    subgraph "Additional Infrastructure"
        F1["Documentation & Internal Tools"]:::infra
        F2["Config & Deployment"]:::infra
    end

    %% Connections from Clients to DEX Server Core
    A1 -->|"order_API"| B1
    A2 -->|"trading_cmds"| B1
    A3 -->|"websocket_API"| B1
    A4 -->|"mobile_API"| B1

    %% Internal DEX Server interactions
    B1 -->|"calls"| B2
    B1 -->|"reads/writes"| B3
    B1 -->|"routes_to"| B4

    %% Connection between DEX Server and Protocol layer
    B1 -->|"protocol"| C1

    %% Connection from DEX Server to Blockchain Networks
    B1 -->|"on-chain_settlement"| E1

    %% Bidirectional connection between DEX Server and Tatanka Mesh
    B1 <-->|"decentralized_routing"| D1

    %% Click Events for Client Applications
    click A1 "https://github.com/decred/dcrdex/tree/master/client/cmd/bisonw-desktop"
    click A2 "https://github.com/decred/dcrdex/tree/master/client/asset"
    click A3 "https://github.com/decred/dcrdex/tree/master/client/webserver"
    click A4 "https://github.com/decred/dcrdex/tree/master/companionapp/android"

    %% Click Event for DEX Server Components
    click B1 "https://github.com/decred/dcrdex/tree/master/server"
    click B2 "https://github.com/decred/dcrdex/tree/master/server/auth"
    click B3 "https://github.com/decred/dcrdex/tree/master/server/db"
    click B4 "https://github.com/decred/dcrdex/tree/master/server/asset"

    %% Click Event for Protocol Layer
    click C1 "https://github.com/decred/dcrdex/tree/master/dex"

    %% Click Event for Tatanka Mesh
    click D1 "https://github.com/decred/dcrdex/tree/master/tatanka"

    %% Click Events for Additional Infrastructure
    click F1 "https://github.com/decred/dcrdex/tree/master/internal"
    click F2 "https://github.com/decred/dcrdex/tree/master/client/Dockerfile"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef server fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef protocol fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef p2p fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef infra fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef ext fill:#D6EAF8,stroke:#5499C7,stroke-width:2px;
```
