Architecture Overview

Core design

rCommerce is a single Rust binary with a PostgreSQL backend. Every request flows through the same typed core over the REST API.

Frontends (Next.js, Astro, iOS, Android, POS)
        ↓
    REST + WebSocket API
        ↓
    rCommerce Core (Rust)
    ┌───────────────────────┐
    │ Catalog │ Cart │ Orders│
    │ Payments│ Tax  │ Auth  │
    │ Shipping│ Pricing│ Inventory│
    └───────────────────────┘
        ↓
    PostgreSQL

State changes → events

Every state change in the core fans out as a signed event:

• Webhooks — HTTP POST to registered endpoints
• Email — transactional notifications (order confirmation, shipping, password reset)
• Analytics — event tracking
• OpenTelemetry — traces and metrics

Request lifecycle

1. Client sends REST request
2. Axum router matches handler
3. Middleware: JWT/API key auth, rate limiting, CORS
4. Handler calls service layer
5. Service validates, applies business logic
6. Repository writes to PostgreSQL
7. Events dispatched (webhooks, email, etc.)
8. Response returned to client

Service layer

Each domain has a service:

• ProductService — catalogue management
• CartService — cart operations, bundle expansion
• CheckoutService — checkout flow, tax, shipping
• OrderService — order lifecycle, fulfillment
• AuthService — JWT tokens, API keys, password reset
• NotificationService — email, SMS, webhooks

Services are injected into handlers via Axum state.

Repository layer

Each entity has a repository trait:

#[async_trait]
pub trait ProductRepository {
    async fn find_by_id(&self, id: Uuid) -> Result<Option<Product>>;
    async fn create(&self, product: CreateProduct) -> Result<Product>;
    async fn update(&self, id: Uuid, product: UpdateProduct) -> Result<Product>;
    async fn delete(&self, id: Uuid) -> Result<bool>;
    async fn list(&self, filter: ProductFilter) -> Result<Vec<Product>>;
}

PostgreSQL implementation uses SQLx with compile-time query checking.

Error handling

Custom Error enum with HTTP status code mapping:

pub enum Error {
    Validation(String),      // 400
    Unauthorized(String),    // 401
    Forbidden(String),       // 403
    NotFound(String),        // 404
    Conflict(String),        // 409
    RateLimited(String),     // 429
    Internal(String),        // 500
    // ...
}

Configuration

All configuration in one TOML file. Validated at boot — typos fail fast.

[server]
host = "0.0.0.0"
port = 8080

[database]
db_type = "Postgres"
# ...

Deployment

Single binary, no runtime dependencies:

rcommerce serve -c config.toml

Or via systemd, Docker, or any process manager. Migrations run automatically on startup.