# Order flow

* Order
* Commission
* Wallet
* OME
* Trade
* Cross Order
* Broker
* ExWallet
* Price
* Asset

### Overall View

flowchart TD
Start((Start)) --Order Service--> CreateOrder[Create Order]
CreateOrder --> SendToOME[Send to Internal Match Engine]
SendToOME --OME - Internal Order Book--> MatchOrder[Match Order]
MatchOrder --> Matched{Order Matched?}
Matched --Yes--> CreateTrade
Matched --No - Cross Order Service--> CreateCrossOrder[Create Cross Order]
CreateCrossOrder --Binance/... API--> CreateOrderOnLiquidity[Create Order on Liquidity]
CreateOrderOnLiquidity --Back to cross order service--> OrderDoneOnLiquidity[Order is Completed on Liquidity]
OrderDoneOnLiquidity --Trade Service--> CreateTrade[Create Trade for Matched Orders]
CreateTrade --Wallet Service--> UpdateWallet[Update User Wallet]
UpdateWallet --> End((End))

### Create Order [Order Service]

#### Flow Chart

flowchart TD
Start((Start)) --Order Service--> CreateOrder
CreateOrder --Asset Service-->GetMarket
GetMarket --> MarketExists{Market Exists?}
MarketExists --No--> Reject
Reject --> End
MarketExists --Yes - Commission Service--> GetCommission
GetCommission --Wallet Service-->FreezeCredit
FreezeCredit --> EnoughCredit{Enough Credit?}
EnoughCredit --No--> Reject
EnoughCredit --Yes - Database--> SaveOrder
SaveOrder --Kafka --> PublishOrder
PublishOrder --> End((End))

#### Sequence Diagram

sequenceDiagram
autonumber
    Client ->> Order: createNewOrder

    Order ->> Asset: getMarket
    Asset -->> Order: Market
    
    alt if market errors
        Order -->> Client: fail order
    else if buy or sell tolerance not set
        Order -->> Client: error
    end
    
    Order ->> Commission: getOrderCommission
    Commission -->> Order: orderCommission
    
    alt if commission not found
        Order -->> Client: fail order
    end
    
    Order ->> Wallet: freezeCredit
    Wallet -->> Order: freezeStatus
    
    alt if freeze error
        Order -->> Client: error
    end
    
    Order ->> Database: beginTransaction
    Order ->> Database: insertOrder
    Order ->> Database: updateOrderId
    Order ->> Kafka: publishOrder
    Order ->> Database: commit
    
    alt if database failed
        Order ->> Database: rollback
        
        Order ->> Wallet: unfreezeCredit
        Wallet -->> Order: unfreezeResponse
        
        alt if unfreeze error
            Order ->> Order: log and return error
        end
        
        Order -->> Client: fail order
    else
        Order -->> Client: success
    end
    

### Match Order [OME Service]
#### Flow Chart

flowchart TD
Start((Start)) --> AddToOB[Add to Internal Order Book]
AddToOB --> ProcessOrder[Try To Match Order]
ProcessOrder --> CanMatch{Can Match?}
CanMatch --Yes - Order Service--> NotifyOrderService[Notify Order Service]
NotifyOrderService --Trade Service--> CreateTrade[Create Trade for Matched Orders]
CreateTrade --> End((End))

CanMatch --No--> Wait[Wait - defined in config]
Wait --> NowMatched{Matched?}
NowMatched --Yes - Trade Service-->CreateTrade
NowMatched --No - Order Service--> ChangeOMEType[Change Order OME Type]
ChangeOMEType --Cross Order Service--> CreateCrossOrder[Create Cross Order]
CreateCrossOrder --> End

#### Sequence Diagram

sequenceDiagram
autonumber
    Kafka ->> OME: newOrder
    OME ->> MatchEngine: processOrder
    
        alt if err 
            Order ->> Order: log error and exit
        end
        
        alt if can match
            OME ->> Trade: createTrade
            alt if err 
                OME ->> OME: log
            else
                OME ->> Kafka: commit
            end
        else
            alt if type == 'stoplimit' and market external liq is on
                OME ->> Kafka: createNewCrossOrder and exit
            else
                OME ->> Kafka: commit
                OME ->> OME: insertOrderTimeout
            end
        end
        
        OME ->> OME: start lock
        alt if order timed out
            OME ->> MatchEngine: cancelOrder 
            alt if ok
                OME ->> Kafka: newCrossOrder
                alt if error 
                    OME ->> OME: log
                end
                OME ->> Kafka: changeOrderOMEType
                alt if error
                    OME ->> OME: log
                end
            end
            OME ->> OME: delete order from timeout map
        end
        OME ->> OME: release lock

### Create Cross Order [Cross Order Service]

#### Flow Chart

#### Sequence Diagram

sequenceDiagram
autonumber
    Kafka -) CrossOrder: newOrder
    CrossOrder ->> Database: insert
    Database -->> CrossOrder: insertResponse
    CrossOrder ->> Asset: getMarket
    Note Left Of Database: change to local db
    Asset -->> CrossOrder: Market
    CrossOrder ->> Broker: createOrder
    Broker ->> CrossOrder: Order
    CrossOrder ->> Database: update
    Database ->> CrossOrder: updateResponse
    alt if not ok
        CrossOrder ->> Retry[x]: retry
    end
    
    alt watch order job
        CrossOrder ->> Database: getPendingOrders
        Database -->> CrossOrder: []Order
        loop orders
            CrossOrder ->> Broker: getOrder
            alt if order execQty changed
                CrossOrder -) Kafka: requestNewFakeOrder
            else if order cancelled and execQty not changed
                CrossOrder -) Kafka: publishWalletCancel
            end
            CrossOrder ->> Database: update
        end
    end
    
    Kafka -) CrossOrder: newFakeOrderCreated
    CrossOrder ->> Database: getOrder
    CrossOrder -) Kafka: publishTrade
    
    alt if order is cancelled
        CrossOrder -) Kafka: publishCancelReply
        CrossOrder -) Kafka: publishOrderStatusUpdate
    end

### order / createFakeOrder

sequenceDiagram
    Kafka -) Order: createNewFakeOrder
    Order ->> Database: beginTransaction
    Order ->> Database: insertOrder
    Order ->> Database: updateOrderId
    Order -) Kafka: publishOrder
    Order ->> Database: commit
    
    alt if database failed
        Order ->> Database: rollback
        Order ->> Order: log
    else
        Order ->> Kafka: commit offset
    end

### trade / newTrade

sequenceDiagram
autonumber
    Kafka -) Trade: newTrade
    Trade -) Wallet: updateBalance
    Trade -) MDP[x]: updateMarketData
    Trade -) Order: updateOrderStatus
    

### wallet / updateBalance

sequenceDiagram
autonumber
    Kafka -) Wallet: newTrade
    Wallet ->> Database: startTransaction
    Wallet ->> Wallet: check orderId format correct
    alt if not correct
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Wallet: parse userId
    alt if cannot parse
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Wallet: parse order type
    alt if cannot parse
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Wallet: parse asset
    alt if cannot parse
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Database: getUserWallet
    Database -->> Wallet: user wallet
    alt if error 
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Wallet: calc freeze amount
    
    Wallet ->> Database: get wallet for asset
    alt if error
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    alt if more than frozen amount
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Database: unfreeze
    alt if error
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Wallet: calc available amount
    
    Wallet ->> Database: get wallet for asset
    alt if error
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Database: update available amount (balance)
    alt if error
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Database: get user wallet
    alt if error
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Wallet: create exchange income record
    
    Wallet ->> Database: get wallet asset
    alt if error
        Wallet ->> Database: createWalletAsset
        alt if error
            Wallet ->> Database: rollback
            Wallet ->> Wallet: log
        end
    end
    
    Wallet ->> Database: update opposite wallet asset record
    alt if error
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    end
    
    Wallet ->> Database: insert income record
    alt if error
        Wallet ->> Database: rollback
        Wallet ->> Wallet: log
    else
        Wallet ->> Kafka: commit
    end
    

### order / cancelOrder

sequenceDiagram
autonumber

Client ->> Order: cancelOrder

alt if order not found
    Order ->> Client: fail cancel
else if order done
    Order ->> Client: fail cancel
else if order is already cancelled
    Order ->> Client: fail cancel
end

Order ->> Database: startTransaction
Order ->> Database: update order stutus to cancel

alt if db error
    Order ->> Database: rollback
    Order ->> Client: fail cancel
end

alt if order is internal
    Order ->> Kafka: publishCancelOrder
    alt if error
        Order ->> Database: rollback
        Order ->> Client: fail cancel
    end
    
    alt if order status is processing
        Order ->> Kafka: publishWalletCancel
        
        alt if error
            Order ->> Database: rollback
            Order ->> Client: fail cancel
        end
    end
    
else if order is crossOrder
    Order ->> Kafka: publishCancelCrossOrder
    alt if error
        Order ->> Database: rollback
        Order ->> Client: fail cancel
    end
end

Order ->> Database: commit
Order ->> Client: success

<!-- ### OME / cancel

sequenceDiagram
autonumber

### crossOrder / cancel

sequenceDiagram
autonumber

CrossOrder ->> Database: getOrder
alt if error
    CrossOrder ->> CrossOrder: log and exit
end

alt if order status == not executed
    CrossOrder ->> Database: update status
    alt if error
        CrossOrder ->> CrossOrder: log and exit
    end
    
    CrossOrder ->> Kafka: publishWalletCancel
    CrossOrder ->> Kafka: publishOrderStatus
    alt if error 
        CrossOrder ->> CrossOrder: log and exit
    end
    
else
    CrossOrder ->> Broker: getOrder
    alt if error
        CrossOrder ->> CrossOrder: log and exit
    end
    
    CrossOrder ->> Database: update order status to pending cancel
    alt if error
        CrossOrder ->> CrossOrder: log and exit
    end
end

CrossOrder ->> Kafka: commit

### order / createOrder (revised)

sequenceDiagram
autonumber
    Client ->> Order: createNewOrder
    Order ->> Database: getMarket
    Database -->> Order: market
    alt if error
        Order -->> Client: fail order
    end
    Order ->> Database: getOrderCommission
    Database -->> Order: commission
    alt if error
        Order -->> Client: fail order
    end
    Order ->> Database: getBalance
    Database -->> Order: balance
    alt not enough balance
        Order ->> Client: fail order
    end
    Order ->> Database: createNewTransaction
    Order ->> Database: insertPendingOrder
    Order ->> Database: insertFreezeCreditEvent
    Order ->> Database: commitTransaction
    alt if commit failed
        Order ->> Client: fail order
    else 
        Order ->> Client: success order
    end

### order / after freeze credit (revised)

sequenceDiagram
    Wallet -) Order: asset freeze
    Order ->> Database: createNewTransaction
    Order ->> Database: updateOrderStatus
    Order ->> Database: insertNewOrderEvent
    Order ->> Database: commitTransaction
    loop if commit failed
        Order ->> Retry: retry
    end

### things we need to do

- distributed transaction -> orchestration saga + outbox
- better logging and logging format
- add message id to kafka
- add request id to api gateway (idempotency)
- retry strategy (retry, fail)
- maintenance mode
- distributed tracing

### Tasks

- Wrapping Kafka package for additional features
- Developing outbox package
- Developing CDC package for outbox
- Developing Retry package
- Developing distributed tracing package (Configs: request id, trace id, ...) (open tracing protocole)
- Adding new packages to all micro services + test
- Developing health check for some of micro services
- Error tracking(sentry), Error logs(Greylog), Monitoring(promoteus)
- securing transactions with sign check(rsa 128 bit)
- Securing Balance model by reflecting coresponding transactions in wallet db (P n L data)
-
-