Villa Backend SDK — Design

This document explains how the SDK is structured, why it is organized this way, and how data flows from login through order construction, validation, and payment.

Goals

The SDK exists to give developers a **small, predictable surface area** for Villa Market backend operations:

1. Authenticate a shopper via **AWS Cognito**

2. Build an **order** that matches the official villaMasterSchema contract

3. **Validate** that order locally and against backend pricing APIs

4. **Pay** using the Villa payment endpoints

Each step is isolated in its own module so it can be tested, replaced, or extended independently.

High-level architecture

The SDK uses a **layered architecture** with a thin facade on top:

┌─────────────────────────────────────────────────────────────┐
│                        VillaClient                          │
│  (facade: wires services, login(), health(), context mgr)   │
└───────────────┬───────────────┬───────────────┬─────────────┘
                │               │               │
        ┌───────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
        │     auth     │ │   orders    │ │  payments   │
        │ CognitoAuth  │ │ OrderService│ │PaymentService│
        └───────┬──────┘ └──────┬──────┘ └──────┬──────┘
                │               │               │
                └───────────────┼───────────────┘
                                │
                    ┌───────────▼───────────┐
                    │      validation       │
                    │ schema + API checks   │
                    └───────────┬───────────┘
                                │
                    ┌───────────▼───────────┐
                    │         http          │
                    │ requests + auth hdrs  │
                    └───────────┬───────────┘
                                │
                    ┌───────────▼───────────┐
                    │        config         │
                    │ URLs, env, API paths  │
                    └───────────────────────┘

Design principles

Module reference

config.py — configuration

Centralizes all runtime settings:

Payment paths switch by environment:

http.py — transport layer

Wraps requests and adds:

Nothing in http.py knows about orders or payments — it only sends HTTP.

auth/ — AWS Cognito login

User credentials
      │
      ▼
CognitoAuthService.login()
      │
      ▼
boto3 cognito-idp InitiateAuth (USER_PASSWORD_AUTH)
      │
      ▼
AuthTokens (AccessToken, IdToken, RefreshToken)
      │
      ▼
HttpClient.set_bearer_token(IdToken)

orders/ — order construction and CRUD

Three pieces work together:

**OrderBuilder** example flow:

order = (
    OrderBuilder()
    .with_ids(order_id="...", owner_id="...", basket_id="...")
    .with_branch("1000")
    .add_product(cprcode=25281, quantity=1)
    .with_delivery_shipping(shipping_postcode="10330", shipping_phone="...")
    .with_payment_totals(grand_total=174.0)
    .build()
)

order.to_api_payload() emits camelCase JSON matching the backend contract.

validation/ — local schema + remote API checks

This is the **pre-payment gate**. Two validators compose into PrePaymentValidator:

#### 1. Local: OrderSchemaValidator

#### 2. Remote: OrderApiValidator

Calls backend pricing/verification APIs:

#### 3. Orchestrator: PrePaymentValidator

Runs a **pipeline** and returns PrePaymentValidationResult:

Step 1: local_schema          → jsonschema against order.yaml
Step 2: drafting check        → reject if isDrafting=true
Step 3: remote_order_exists   → optional GET order
Step 4: calculate_grand_total → compare with expected amount
Step 5: calculate_cost        → confirm cart pricing

Each step appends to result.steps on success or result.errors on failure. The pipeline **stops at the first failure**.

payments/ — card token and card payment

Handles Villa + KBank payment endpoints:

Payment requests use **form-urlencoded** bodies, not JSON, matching the live Villa payment API.

cli/ — command-line interface

Maps 1:1 to SDK modules:

Schema contract

Order shape is defined by villaMasterSchema/order/order.yaml.

Bundled copies live in:

villa_backend_sdk/schemas/
├── order/order.yaml
├── order/genOrderId.yaml
├── webPayment/calculateGrandtotal.yaml
└── calculateCost/getCost.yaml

**Required order fields:** orderId, ownerId, basketId

The SDK keeps schemas in the package so:

Typical checkout sequence

sequenceDiagram
    participant Dev as Application
    participant SDK as VillaClient
    participant Cognito as AWS Cognito
    participant API as shop.villamarket.com

    Dev->>SDK: login(email, password)
    SDK->>Cognito: InitiateAuth
    Cognito-->>SDK: IdToken
    SDK->>SDK: set Bearer token on HttpClient

    Dev->>SDK: OrderBuilder.build()
    Dev->>SDK: pre_payment.validate(order)

    SDK->>SDK: jsonschema (local)
    SDK->>API: POST calculateGrandtotal
    API-->>SDK: grandTotal
    SDK->>API: POST calculateCost
    API-->>SDK: pricing breakdown

    alt validation passed
        Dev->>SDK: payments.create_card_token(...)
        SDK->>API: POST cardtoken
        Dev->>SDK: payments.initiate_card_payment(...)
        SDK->>API: POST cardpayment
        API-->>Dev: redirect URL with status
    else validation failed
        SDK-->>Dev: PrePaymentValidationResult(errors=...)
    end

Error model

All SDK errors inherit from VillaError:

VillaValidationError carries an errors: list[str] with human-readable messages from jsonschema or the validation pipeline.

Extension points

Related documents