Technical Architecture

# Technical Architecture Document

## Project Overview
The SDEX Razor Component Library is a collection of reusable, client-side Razor View Components for integrating Stellar Decentralized Exchange (SDEX) functionalities into .NET applications. These components are packaged as a NuGet package, enabling developers to integrate SDEX trading and portfolio tools seamlessly.

## Architecture Overview
The architecture follows a **client-centric, modular approach**, where each component is a standalone Razor View Component. These components interact directly with the Horizon API using the Stellar DotNet SDK, handling data retrieval, transaction creation, and user interactions on the client side. Models are used where needed to represent and manage data.

## Component Structure

### Real-time Order Book Component
- **Description:** Displays current buy and sell orders from the SDEX, fetched directly from the Horizon API.
- **Technology Stack:** 
  - Razor View Component
  - JavaScript (for real-time updates via AJAX polling)
  - Models (for representing order data)
- **Data Flow:**
  - Makes direct API calls to Horizon to fetch order book data.
  - Uses AJAX or SignalR to handle real-time updates, ensuring the UI stays synchronized.

### Open Orders Component
- **Description:** Displays a list of user’s active orders on the SDEX.
- **Technology Stack:**
  - Razor View Component
  - JavaScript (for periodic updates)
  - Models (for managing order data)
- **Data Flow:**
  - Fetches active orders for the user from Horizon API.
  - User actions trigger API calls to update the displayed data.

### Order Submission Component
- **Description:** A form-based component for users to submit buy/sell orders directly to the SDEX.
- **Technology Stack:**
  - Razor View Component
  - JavaScript (for handling form submissions)
  - Models (for capturing user inputs)
- **Data Flow:**
  - User inputs data into the form.
  - Component uses the Stellar DotNet SDK to create, sign, and submit the transaction to Horizon.

### Order Modification Component
- **Description:** Allows users to modify an existing order on the SDEX.
- **Technology Stack:**
  - Razor View Component
  - JavaScript (for handling modifications)
  - Models (for representing order data)
- **Data Flow:**
  - Fetches existing order details for editing.
  - Cancels existing order then submits the modified order directly to Horizon.

### Order Cancellation Component
- **Description:** Enables users to cancel open orders directly from the component interface.
- **Technology Stack:**
  - Razor View Component
  - JavaScript (for handling cancellation)
  - Models (for managing order data)
- **Data Flow:**
  - Displays cancellable orders.
  - Upon user confirmation, creates and submits a cancellation transaction via the Horizon API.

### Completed Orders Component
- **Description:** Displays a history of completed orders, fetched from the Horizon API.
- **Technology Stack:**
  - Razor View Component
  - JavaScript (for fetching historical data)
  - Models (for representing historical order data)
- **Data Flow:**
  - Fetches user’s completed trades from Horizon and updates the display.

## Technologies & Tools

### Razor View Components
- **Purpose:** Built with Razor syntax and embedded into Razor Pages or MVC Views.
- **Deployment:** Packaged as a NuGet library for easy distribution.
- **JavaScript Integration:** Each component will have embedded JavaScript for handling real-time updates and transaction feedback.

### Stellar DotNet SDK
- **Purpose:** Facilitates direct interaction with the Stellar blockchain and Horizon API.
- **Integration:** Used within the Razor components to create, sign, and submit transactions from the client side.

### JavaScript & AJAX
- **Purpose:** Manages client-side interactions, API calls, and asynchronous data updates.
- **Integration:** Enhances the responsiveness of Razor components.

## Data Flow & Communication

- **Client-Side Data Flow:** All interactions are initiated from the Razor components and managed directly on the client side.
- **API Communication:** Components communicate with the Horizon API for data retrieval, transaction submission, and order management.
- **Real-Time Updates:** Implement AJAX polling or SignalR to maintain live data synchronization with the SDEX.

## Security Considerations

- **Client-Side Transaction Signing:** Transactions are securely signed in the client browser to prevent exposure of secret keys.
- **Rate Limiting:** Implement client-side throttling to avoid exceeding API rate limits.
- **Input Validation:** Ensure robust input validation to prevent injection attacks or malformed transactions.
- **Secure Key Storage:** For development, use secure local storage for keys; recommend hardware wallets for production environments.

## Deployment Strategy

- **NuGet Packaging:** 
  - The components will be bundled as a NuGet package for easy installation and integration into .NET projects.
  - Each component is self-contained with necessary models and JavaScript helpers for plug-and-play functionality.
- **Compatibility:** 
  - Compatible with .NET Core, .NET 5/6/7+, supporting both Visual Studio and Visual Studio Code environments.

## Testing & Validation

- **Unit Testing:** 
  - Use xUnit or NUnit for testing models and API interactions within the components.
  - Mock Horizon API responses for reliable, isolated testing.
- **Client-Side Testing:** 
  - Use Jasmine or similar frameworks to test client-side JavaScript functions.
  - Perform manual and automated UI testing to ensure component responsiveness.

## Documentation & User Guide

- **Developer Documentation:** 
  - Includes setup, configuration, usage, and customization guides for each component.
- **User Guide:** 
  - Provides step-by-step guidance for integrating components, setting up key management, and using SDEX features.

## Future Extensions

- **Additional UI Enhancements:** 
  - Add features like charts, analytics, or asset management in future versions.
- **Soroban Integration:** 
  - Potential integration with Soroban smart contracts to expand functionality for DeFi use cases.