> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# StateSet API

> A high-performance, scalable backend framework built with Rust, Axum, and SeaORM for enterprise-grade applications.

# StateSet API: A Robust Backend Framework

StateSet API is a modern, scalable, and reliable backend system designed for enterprise-grade web services. Built with Rust, it leverages cutting-edge web technologies and best practices to deliver a high-performance infrastructure solution. It is particularly well-suited for e-commerce and manufacturing businesses, adept at handling order management, inventory control, returns processing, warranty management, shipment tracking, and work order handling.

## Core Features

StateSet API is built to handle complex business operations. Here's a breakdown of its key features:

* **Order Management:** Full CRUD operations for orders, support for complex workflows and statuses.
* **Inventory Control:** Real-time tracking across multiple locations, automated reorder point notifications.
* **Returns Processing:** Streamlined return authorization, processing, and integration with refund and exchange systems.
* **Warranty Management:**  Track and manage product warranties, handle automated claim processing.
* **Shipment Tracking:** Real-time integration with major carriers, custom shipment status notifications.
* **Manufacturing & Production:** Supplier management, BOM tracking, and version control.
* **Work Order Handling:** Create and manage work orders, track progress, and manage resource allocation.

## Tech Stack: The Foundation of Performance

Our carefully selected tech stack ensures high performance, scalability, and maintainability.

### Core Technologies

* **Language:** [Rust](https://www.rust-lang.org/) (for performance, safety, and concurrency)
* **Web Framework:** [Axum](https://github.com/tokio-rs/axum/) (a lightweight, async, and fast web framework)
* **Database:** [PostgreSQL](https://www.postgresql.org/) (for robust, reliable data storage) with [SQLx](https://github.com/launchbadge/sqlx) (for async operations).

### ORM and Query Building

* [SeaORM](https://www.sea-ql.org/SeaORM) (a powerful async ORM for Rust).

### API Protocols and Services

* **REST:** Implemented natively with Axum.
* **GraphQL:** Implemented using [Async-GraphQL](https://async-graphql.github.io/) for a high-performance GraphQL API.
* **gRPC:** Built with [Tonic](https://github.com/hyperium/tonic) for efficient, type-safe gRPC support.

### Caching and Messaging

* **Caching:** [Redis](https://redis.io/) for high-speed data caching.
* **Message Queue:** [RabbitMQ](https://www.rabbitmq.com/) for reliable asynchronous processing.

### Observability

* **Metrics:** [Prometheus](https://prometheus.io/) for detailed system monitoring.
* **Tracing:** [OpenTelemetry](https://opentelemetry.io/) with [Jaeger](https://www.jaegertracing.io/) for distributed tracing.
* **Logging:** [slog](https://docs.rs/slog/latest/slog/) for structured, efficient logging.

### Technological Advantages:

* **Rust's Performance & Safety:** Guarantees memory safety and prevents common programming errors, leading to a highly reliable and performant API.
* **Asynchronous Operations:** Utilizing Rust's async capabilities for high-throughput and non-blocking processing.
* **Comprehensive Observability:** Enables proactive maintenance and rapid issue resolution.
* **Flexible API Protocols:** Supports various API protocols, ensuring integration with different client applications and services.

### Use Cases:

* **E-commerce Platforms:** Efficiently manage orders, inventory, shipments, and customer interactions.
* **Manufacturing Systems:** Streamline production workflows, inventory control, supplier management, and quality assurance.
* **Enterprise Solutions:** Provides a scalable backend infrastructure for a wide variety of business operations and services.

## Architecture: Modular and Event-Driven

StateSet API adopts a modular, asynchronous, event-driven architecture designed for scalability and maintainability.

```mermaid theme={null}
flowchart TB
    Client[Client]
    
    subgraph API["StateSet API"]
        direction TB
        Handlers[Handlers]
        Commands[Commands]
        Queries[Queries]
        Services[Services]
        Models[Models]
        Middleware[Middleware]
    end
    
    subgraph Core["Core Technologies"]
        direction LR
        Rust[Rust]
        Axum[Axum]
        PostgreSQL[PostgreSQL]
    end
    
    subgraph Data["Data Layer"]
        direction LR
        SeaORM[SeaORM]
        SQLx[SQLx]
    end
    
    subgraph Protocols["API Protocols"]
        direction TB
        REST[REST]
        GraphQL[Async-GraphQL]
        gRPC[Tonic gRPC]
    end
    
    subgraph Cache["Caching & Messaging"]
        direction LR
        Redis[Redis]
        RabbitMQ[RabbitMQ]
    end
    
    subgraph Observability["Observability"]
        direction TB
        Prometheus[Prometheus]
        OpenTelemetry[OpenTelemetry]
        Jaeger[Jaeger]
        Slog[Slog]
    end
    
    Client --> Protocols
    Protocols --> API
    
    API --> Core
    API --> Data
    API --> Cache
    API --> Observability
    
    Core --> PostgreSQL
    Data --> PostgreSQL
```

### Key Components

* **Services:** Implement the core business logic for specific functionalities.
* **Handlers:** Process incoming HTTP requests, routing them to the appropriate logic.
* **Commands:** Handle operations that modify data or state in the system (writes).
* **Queries:** Handle read operations, retrieving data without modifying it.
* **Events:** Enable asynchronous communication and processing through event triggers.
* **Models:** Represent domain entities, providing a structured data layer.
* **Middleware:** Handle cross-cutting concerns like authentication, rate limiting, and logging.

## Performance and Reliability

StateSet API is engineered for high performance and reliability:

* Handles 10,000+ requests per second on a single node (This is a claim. If you have concrete benchmarks include them here or state in which conditions you measured this).
* Scales horizontally to accommodate increased load.
* Designed for 99.99% uptime SLA (Include specifics if this is part of an actual SLA).

## Code Examples

Here are some representative code snippets to demonstrate the implementation.

### Axum Web Service Entrypoint

This code sets up the Axum web service, including routes, middleware, and integration with other services.

```rust theme={null}
#[tokio::main]
async fn main() -> Result<(), AppError> {
    dotenv().ok();
    let config = Arc::new(config::load()?);
    let log = setup_logger(&config);

    info!(log, "Starting StateSet API";
        "environment" => &config.environment,
        "version" => env!("CARGO_PKG_VERSION")
    );

    let app_state = build_app_state(&config, &log).await?;

    let schema = Arc::new(graphql::create_schema(
        app_state.services.order_service.clone(),
        // ... other service clones
    ));

    setup_telemetry(&config)?;

    // Spawn event processing
    tokio::spawn(events::process_events(
       app_state.event_sender.subscribe(),
       app_state.services.clone(),
       log.clone(),
    ));

    // Start gRPC server (conditionally included)
    #[cfg(feature = "grpc")]
    let grpc_server = grpc_server::start(config.clone(), app_state.services.clone()).await?;

    let app = Router::new()
        .route("/health", get(health::health_check))
        .nest("/orders", handlers::orders::routes())
        // ... other route nests
        .route("/proto_endpoint", post(handle_proto_request))
        .layer(Extension(app_state))
        .layer(Extension(schema))
        .layer(TraceLayer::new_for_http())
        .layer(CompressionLayer::new())
        .layer(axum::middleware::from_fn(auth::auth_middleware))
        .layer(axum::middleware::from_fn(rate_limiter::rate_limit_middleware));

    let addr = format!("{}:{}", config.host, config.port);
    info!(log, "StateSet API server running"; "address" => &addr);
    axum::Server::bind(&addr.parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();

    info!(log, "Shutting down");
    Ok(())
}
```

> This shows the main entry point of the server including the config loading, setup of global services, the route definition, telemetry and the server startup

### Handlers: API Request Routing

Here are some examples of how API requests are routed to the correct command.

#### Create Order Handler

```rust theme={null}
async fn create_order(
    State(order_service): State<Arc<OrderService>>,
    Json(command): Json<CreateOrderCommand>,
) -> Result<impl IntoResponse, ServiceError> {
    let result = command.execute(order_service).await?;
    Ok(Json(result))
}
```

> This handler pulls the OrderService from the application state and calls the execute method on the CreateOrderCommand

#### Close Return Handler

```rust theme={null}
async fn close_return(
    State(return_service): State<Arc<ReturnService>>,
    Path(return_id): Path<i32>,
) -> Result<impl IntoResponse, ServiceError> {
    let command = CloseReturnCommand { return_id };
    let closed_return = command.execute(return_service).await?;
    Ok(Json(closed_return))
}
```

> This handler pulls the ReturnService from the application state and calls the execute method on the CloseReturnCommand

### Commands: Business Logic Execution

The following shows the Create Order and Close Return commands which handle the business logic.

#### Create Order Command

```rust theme={null}
#[derive(Debug, Serialize, Deserialize, Validate)]
pub struct CreateOrderCommand {
    pub customer_id: Uuid,
    #[validate(length(min = 1, message = "At least one item is required"))]
    pub items: Vec<OrderItem>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct OrderItem {
    pub product_id: Uuid,
    #[validate(range(min = 1))]
    pub quantity: i32,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct CreateOrderResult {
    pub id: Uuid,
    pub customer_id: Uuid,
    pub status: String,
    pub created_at: DateTime<Utc>,
    pub items: Vec<OrderItem>,
}

#[async_trait::async_trait]
impl Command for CreateOrderCommand {
    type Result = CreateOrderResult;

    #[instrument(skip(self, db_pool, event_sender))]
    async fn execute(
        &self,
        db_pool: Arc<DbPool>,
        event_sender: Arc<EventSender>,
    ) -> Result<Self::Result, ServiceError> {
        // Validates the incoming command. Returns a validation error if invalid
        self.validate().map_err(|e| {
            ORDER_CREATION_FAILURES.inc();
            let msg = format!("Invalid input: {}", e);
            error!("{}", msg);
            ServiceError::ValidationError(msg)
        })?;
        let db = db_pool.as_ref();
        let saved_order = self.create_order(db).await?;
        self.log_and_trigger_event(&event_sender, &saved_order).await?;
        ORDER_CREATIONS.inc();
        Ok(CreateOrderResult {
            id: saved_order.id,
            customer_id: saved_order.customer_id,
            status: saved_order.status,
            created_at: saved_order.created_at.and_utc(),
            items: self.items.clone(),
        })
    }
}
// ... create order implementation
```

> This shows the command definition, validation, and execution of the create order command.

#### Close Return Command

```rust theme={null}
#[derive(Debug, Serialize, Deserialize)]
pub struct CloseReturnCommand {
    pub return_id: Uuid,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct CloseReturnResult {
    pub id: Uuid,
    pub object: String,
    pub completed: bool,
}

#[async_trait::async_trait]
impl Command for CloseReturnCommand {
    type Result = CloseReturnResult;

    #[instrument(skip(self, db_pool, event_sender))]
    async fn execute(
        &self,
        db_pool: Arc<DbPool>,
        event_sender: Arc<EventSender>,
    ) -> Result<Self::Result, ServiceError> {
        let db = db_pool.as_ref();
        let completed_return = self.close_return(db).await?;
        self.log_and_trigger_event(&event_sender, &completed_return)
            .await?;
        Ok(CloseReturnResult {
            id: completed_return.id,
            object: "return".to_string(),
            completed: true,
        })
    }
}

// ... close return implementation

```

> This shows the command definition, and execution of the close return command.

### Queries: Data Retrieval

These show the two return queries used by the application.

#### Get Returns By Order Query

```rust theme={null}
#[derive(Debug, Serialize, Deserialize)]
pub struct GetReturnsByOrderQuery {
    pub order_id: i32,
}

#[async_trait]
impl Query for GetReturnsByOrderQuery {
    type Result = Vec<Return::Model>;

    async fn execute(&self, db_pool: Arc<DbPool>) -> Result<Self::Result, ServiceError> {
        let db = db_pool.get().map_err(|_| ServiceError::DatabaseError)?;
        Return::find()
            .filter(Return::Column::OrderId.eq(self.order_id))
            .all(&db)
            .await
            .map_err(|_| ServiceError::DatabaseError)
    }
}
```

> This shows how we can find the returns based on the order ID using SeaORM

#### Get Returns By Date Range Query

```rust theme={null}
#[derive(Debug, Serialize, Deserialize)]
pub struct GetReturnsByDateRangeQuery {
    pub start_date: DateTime<Utc>,
    pub end_date: DateTime<Utc>,
    pub limit: u64,
    pub offset: u64,
}

#[async_trait]
impl Query for GetReturnsByDateRangeQuery {
    type Result = Vec<Return::Model>;

    async fn execute(&self, db_pool: Arc<DbPool>) -> Result<Self::Result, ServiceError> {
        let db = db_pool.get().map_err(|_| ServiceError::DatabaseError)?;
        Return::find()
            .filter(Return::Column::CreatedAt.between(self.start_date, self.end_date))
            .order_by_desc(Return::Column::CreatedAt)
            .limit(self.limit)
            .offset(self.offset)
            .all(&db)
            .await
            .map_err(|_| ServiceError::DatabaseError)
    }
}

```

> This shows how we can find the returns based on a date range using SeaORM.

<Card title="SeaORM" icon="lightbulb" iconType="duotone" color="#2563eb" href="https://www.sea-ql.org/blog/2024-08-04-sea-orm-1.0/">
  To learn more about SeaORM, check out [this article](https://www.sea-ql.org/blog/2024-08-04-sea-orm-1.0/).
</Card>

## Acknowledgments

We express our gratitude to the open-source community and the creators of the following libraries:

* [Axum](https://github.com/tokio-rs/axum/) for the powerful web framework.
* [SeaORM](https://www.sea-ql.org/SeaORM) for providing a robust ORM.
* [Tonic](https://github.com/hyperium/tonic) for enabling gRPC support.
* [Async-GraphQL](https://async-graphql.github.io/) for efficient GraphQL handling.