{"id":19072892,"url":"https://github.com/puneethkumarck/trading-api-kotlin","last_synced_at":"2026-04-17T14:38:17.300Z","repository":{"id":261235480,"uuid":"883391670","full_name":"Puneethkumarck/trading-api-kotlin","owner":"Puneethkumarck","description":"Implementation of trading limit order placement and querying order-book and trade-history in kotlin","archived":false,"fork":false,"pushed_at":"2024-11-14T08:57:45.000Z","size":110,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-02T16:54:57.000Z","etag":null,"topics":["hexagonal-architecture","kotlin","springboot"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Puneethkumarck.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-04T22:10:01.000Z","updated_at":"2024-11-14T08:57:50.000Z","dependencies_parsed_at":"2024-11-05T13:33:56.355Z","dependency_job_id":"51b58f8e-ebcd-40b8-8683-852bbedfe3b7","html_url":"https://github.com/Puneethkumarck/trading-api-kotlin","commit_stats":null,"previous_names":["puneethkumarck/trading-api-kotlin"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Puneethkumarck%2Ftrading-api-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Puneethkumarck%2Ftrading-api-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Puneethkumarck%2Ftrading-api-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Puneethkumarck%2Ftrading-api-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Puneethkumarck","download_url":"https://codeload.github.com/Puneethkumarck/trading-api-kotlin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240124228,"owners_count":19751440,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hexagonal-architecture","kotlin","springboot"],"created_at":"2024-11-09T01:44:31.296Z","updated_at":"2026-04-17T14:38:17.270Z","avatar_url":"https://github.com/Puneethkumarck.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=Puneethkumarck_trading-api)](https://sonarcloud.io/summary/new_code?id=Puneethkumarck_trading-api)\n[![SonarCloud](https://sonarcloud.io/images/project_badges/sonarcloud-white.svg)](https://sonarcloud.io/summary/new_code?id=Puneethkumarck_trading-api)\n\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=Puneethkumarck_trading-api\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=Puneethkumarck_trading-api)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=Puneethkumarck_trading-api\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=Puneethkumarck_trading-api)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=Puneethkumarck_trading-api\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=Puneethkumarck_trading-api)\n[![Deployed on Railway](https://railway.app/button.svg)](https://railway.app/template/aYpw1-?referralCode=F4Yi_e)\n[\u003cimg src=\"https://run.pstmn.io/button.svg\" alt=\"Run In Postman\" style=\"width: 128px; height: 32px;\"\u003e](https://god.gw.postman.com/run-collection/685178-34771dde-0c1a-4fa2-8613-14a572120e88?action=collection%2Ffork\u0026source=rip_markdown\u0026collection-url=entityId%3D685178-34771dde-0c1a-4fa2-8613-14a572120e88%26entityType%3Dcollection%26workspaceId%3De03b2ab3-447a-4a5f-8818-be163b36a6e7#?env%5Brailway%5D=W3sia2V5IjoidXJsIiwidmFsdWUiOiJodHRwczovL2NyeXB0by1hcGktcHJvZHVjdGlvbi00NzNhLnVwLnJhaWx3YXkuYXBwIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQifV0=)\n\n# Trading API\n\nA Kotlin-based cryptocurrency trading API that provides order book management, limit order processing, and trade history tracking capabilities.\n\n## Table of Contents\n- [Overview](#overview)\n- [Features](#features)\n- [Technology Stack](#technology-stack)\n- [Architecture](#architecture)\n- [API Documentation](#api-documentation)\n- [Component Diagrams](#component-diagrams)\n- [Sequence Diagrams](#sequence-diagrams)\n- [Class Diagrams](#class-diagrams)\n- [Setup and Configuration](#setup-and-configuration)\n- [Code Quality](#code-quality)\n\n## Overview\n\nThe Trading API is a Spring Boot application that implements a cryptocurrency trading platform with support for:\n- Order book management\n- Limit order processing\n- Trade history tracking\n\n## Features\n\n### 1. Order Book Management\n- Maintains buy (bid) and sell (ask) orders\n- Aggregated view of orders at each price level\n\n### 2. Limit Order Processing\n- Support for BUY and SELL orders\n- Partial and full order fills\n\n### 3. Trade History\n- Real-time trade execution recording\n- Historical trade lookup\n- Trade aggregation by currency pair\n- Pagination support\n\n### 4. Additional Features\n- Idempotent order submission\n- Concurrency handling\n- Input validation\n- Error handling with appropriate HTTP status codes\n- API documentation with OpenAPI/Swagger\n- Spring Security basic authentication\n\n## Technology Stack\n\n- **Framework**: Spring Boot 3.3.4\n- **Language**: Java 21, Kotlin\n- **Build Tool**: Gradle\n- **Testing**: JUnit 5, Kotlin mock\n- **Documentation**: OpenAPI/Swagger\n- **Code Quality**:\n    - SonarCloud\n    - JaCoCo for code coverage\n    - Spotless for code formatting\n- **Libraries**:\n    - MapStruct for object mapping\n    - Jackson for JSON processing\n    - Lombok for boilerplate reduction\n    - Spring Validation\n\n## Architecture\n\nThe application follows a hexagonal (ports and adapters) architecture pattern with the following layers:\n\n1. **API Layer** (Application)\n    - Controllers\n    - DTOs\n    - Mappers\n    - Exception Handlers\n\n2. **Domain Layer**\n    - Order Book Logic\n    - Limit Order Processing\n    - Trade Management\n    - Domain Models\n\n3. **Infrastructure Layer**\n    - Repositories\n    - Service Adapters\n    - Entity Classes\n\n### Component Diagram\n\n```mermaid\ngraph LR\n%% Styling\n    classDef applicationBlock fill:#e1f5fe,stroke:#01579b,stroke-width:2px\n    classDef domainBlock fill:#f3e5f5,stroke:#4a148c,stroke-width:2px\n    classDef infrastructureBlock fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px\n    classDef controller fill:#bbdefb,stroke:#1976d2,stroke-width:1px\n    classDef service fill:#e1bee7,stroke:#7b1fa2,stroke-width:1px\n    classDef repository fill:#c8e6c9,stroke:#388e3c,stroke-width:1px\n\n%% Application Layer Block\n    subgraph ApplicationLayer[\" Application Layer \"]\n        direction TB\n        subgraph Controllers[\" Controllers \"]\n            LC[LimitOrderController]\n            OBC[OrderBookController]\n            THC[TradeHistoryController]\n        end\n\n        subgraph Mappers[\" Mappers \"]\n            LODM[LimitOrderDtoMapper]\n            OBDM[OrderBookDtoMapper]\n            THDM[TradeHistoryDtoMapper]\n        end\n    end\n\n%% Domain Layer Block\n    subgraph DomainLayer[\" Domain Layer \"]\n        direction TB\n        subgraph CoreServices[\" Core Services \"]\n            LOCH[LimitOrderCommandHandler]\n            OP[OrderProcessor]\n            OBQH[OrderBookQueryHandler]\n            THQH[TradeHistoryQueryHandler]\n        end\n\n        subgraph DomainModel[\" Domain Model \"]\n            OB[OrderBook]\n            LO[LimitOrder]\n            TH[Trade]\n        end\n\n        subgraph Validators[\" Validators \"]\n            OBIV[OrderBookIdemPotencyValidator]\n        end\n    end\n\n%% Infrastructure Layer Block\n    subgraph InfrastructureLayer[\" Infrastructure Layer \"]\n        direction TB\n        subgraph Adaptors[\" Repository Adaptors \"]\n            OBA[OrderBookRepositoryAdaptor]\n            LOA[LimitOrderRepositoryAdaptor]\n            THA[TradeHistoryRepositoryAdaptor]\n        end\n\n        subgraph Storage[\" Storage \"]\n            IMO[InMemoryOrderRepository]\n            IMOB[InMemoryOrderBookRepository]\n            IMT[InMemoryTradeRepository]\n        end\n    end\n\n%% Relationships - Application to Domain\n    LC --\u003e|\"Maps DTO\"| LODM\n    LODM --\u003e|\"Creates Command\"| LOCH\n    OBC --\u003e|\"Queries\"| OBQH\n    THC --\u003e|\"Queries\"| THQH\n\n%% Relationships - Domain Internal\n    LOCH --\u003e|\"Uses\"| OP\n    LOCH --\u003e|\"Validates\"| OBIV\n    OP --\u003e|\"Manages\"| OB\n    OBQH --\u003e|\"Reads\"| OB\n    THQH --\u003e|\"Reads\"| TH\n\n%% Relationships - Domain to Infrastructure\n    OP --\u003e|\"Persists\"| OBA\n    OP --\u003e|\"Records\"| THA\n    OBIV --\u003e|\"Checks\"| LOA\n\n%% Relationships - Infrastructure Internal\n    OBA --\u003e|\"Stores\"| IMOB\n    LOA --\u003e|\"Stores\"| IMO\n    THA --\u003e|\"Stores\"| IMT\n\n%% Apply styles\n    class ApplicationLayer applicationBlock\n    class DomainLayer domainBlock\n    class InfrastructureLayer infrastructureBlock\n\n    class LC,OBC,THC controller\n    class LOCH,OP,OBQH,THQH service\n    class IMO,IMOB,IMT repository\n\n%% Styling for subgraphs\n    style Controllers fill:#e3f2fd,stroke:#1565c0\n    style Mappers fill:#e3f2fd,stroke:#1565c0\n    style CoreServices fill:#f3e5f5,stroke:#6a1b9a\n    style DomainModel fill:#f3e5f5,stroke:#6a1b9a\n    style Validators fill:#f3e5f5,stroke:#6a1b9a\n    style Adaptors fill:#e8f5e9,stroke:#2e7d32\n    style Storage fill:#e8f5e9,stroke:#2e7d32\n\n%% Layer Labels\n    style ApplicationLayer fill:none,stroke:#01579b,stroke-width:4px\n    style DomainLayer fill:none,stroke:#4a148c,stroke-width:4px\n    style InfrastructureLayer fill:none,stroke:#1b5e20,stroke-width:4px\n```\n\n\n### Class Diagrams\n\n#### Order Book Classes\n\n```mermaid\nclassDiagram\n    class OrderBook {\n        +String currencyPair\n        +TreeMap\u003cBigDecimal, OrderBookLevel\u003e asks\n        +TreeMap\u003cBigDecimal, OrderBookLevel\u003e bids\n        +Instant lastChange\n        +Long sequenceNumber\n    }\n\n    class OrderBookLevel {\n        +OrderBookSide side\n        +BigDecimal quantity\n        +BigDecimal price\n        +String currencyPair\n        +int orderCount\n    }\n\n    class OrderBookRepository {\n        \u003c\u003cinterface\u003e\u003e\n        +findByCurrencyPair(String): Optional\u003cOrderBook\u003e\n        +save(OrderBook): Optional\u003cOrderBook\u003e\n    }\n\n    OrderBook --\u003e OrderBookLevel\n    OrderBookRepository --\u003e OrderBook\n```\n\n#### Limit Order Classes\n\n```mermaid\nclassDiagram\n    class LimitOrderCommand {\n        +LimitOrder limitOrder\n        +String customerOrderId\n    }\n\n    class LimitOrder {\n        +OrderBookSide side\n        +BigDecimal quantity\n        +BigDecimal price\n        +String currencyPair\n        +OrderStatus status\n    }\n\n    class OrderProcessor {\n        \u003c\u003cabstract\u003e\u003e\n        #processOrder()\n        #matchOrders()\n        #placeOrder()\n    }\n\n    class BuyOrderProcessor {\n        +getMatchingSide()\n        +getPlacementSide()\n        +canMatch()\n    }\n\n    class SellOrderProcessor {\n        +getMatchingSide()\n        +getPlacementSide()\n        +canMatch()\n    }\n\n    LimitOrderCommand --\u003e LimitOrder\n    OrderProcessor \u003c|-- BuyOrderProcessor\n    OrderProcessor \u003c|-- SellOrderProcessor\n```\n\n### Sequence Diagrams\n\n#### Place Limit Order\n\n```mermaid\nsequenceDiagram\n    participant C as Client\n    participant LC as LimitOrderController\n    participant LH as LimitOrderCommandHandler\n    participant IV as IdemPotencyValidator\n    participant OP as OrderProcessor\n    participant OR as OrderRepository\n    participant TR as TradeRepository\n\n    C-\u003e\u003eLC: POST /api/v1/orders\n    LC-\u003e\u003eLH: handle(command)\n    LH-\u003e\u003eIV: validate(command)\n    IV-\u003e\u003eOR: findByOrderId()\n    IV-\u003e\u003eOR: save(command)\n    LH-\u003e\u003eOP: processOrder()\n    \n    alt Order Matches\n        OP-\u003e\u003eTR: save(trade)\n    else No Match\n        OP-\u003e\u003eOR: save(orderBook)\n    end\n    \n    LC--\u003e\u003eC: OrderResponse\n```\n\n#### Get Order Book\n\n```mermaid\nsequenceDiagram\n    participant C as Client\n    participant OC as OrderBookController\n    participant OH as OrderBookQueryHandler\n    participant OR as OrderBookRepository\n    \n    C-\u003e\u003eOC: GET /api/v1/orders/{pair}\n    OC-\u003e\u003eOH: getOrderBook(pair)\n    OH-\u003e\u003eOR: findByCurrencyPair(pair)\n    \n    alt Order Book Found\n        OR--\u003e\u003eOH: OrderBook\n        OH--\u003e\u003eOC: OrderBook\n        OC--\u003e\u003eC: OrderBookResponse\n    else Not Found\n        OR--\u003e\u003eOH: Empty\n        OH--\u003e\u003eOC: OrderBookNotFoundException\n        OC--\u003e\u003eC: 404 Not Found\n    end\n```\n\n#### Get Trade History\n\n```mermaid\nsequenceDiagram\n    participant C as Client\n    participant TC as TradeHistoryController\n    participant TH as TradeHistoryQueryHandler\n    participant TR as TradeHistoryRepository\n    \n    C-\u003e\u003eTC: GET /api/v1/trades/{pair}/history\n    TC-\u003e\u003eTH: getTradeHistory(pair, limit)\n    TH-\u003e\u003eTR: findRecentTradesByCurrencyPair(pair, limit)\n    TR--\u003e\u003eTH: List\u003cTrade\u003e\n    TH--\u003e\u003eTC: List\u003cTrade\u003e\n    TC--\u003e\u003eC: List\u003cTradeHistoryResponse\u003e\n```\n\n## Setup and Configuration\n\n### Prerequisites\n- Java 21\n- Gradle 8.x\n\n### Build and Run\n```bash\n# Build the project\n./gradlew clean build\n```\n\n```bash\n# Run tests\n./gradlew test\n```\n\n```bash\n# Run the application\n./gradlew bootRun\n```\n\n### API Documentation\nThe API documentation is available at : [swagger](https://trading-api-production-057a.up.railway.app/swagger-ui/index.html)\n\n### Code Style\nThe project uses Spotless with Eclipse formatter for consistent code style. Format the code using:\n```bash\n./gradlew spotlessApply\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuneethkumarck%2Ftrading-api-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuneethkumarck%2Ftrading-api-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuneethkumarck%2Ftrading-api-kotlin/lists"}