​
System Architecture

Loyalty.lt is built on a modern, scalable architecture designed to handle loyalty programs for businesses of all sizes. The platform is organized into distinct API layers that serve different use cases and access levels.

​
Architecture Overview

Loyalty.lt Architecture Diagram
The Loyalty.lt platform consists of three main components:
  1. Backend API - Laravel-based REST API with PostgreSQL database
  2. Frontend Applications - Multiple specialized applications for different users
  3. SDK Libraries - Developer tools for easy integration

​
API Layers

The platform provides three distinct API layers, each optimized for specific use cases and user types.

​
Shop APIs

Purpose: Direct shop integration for basic loyalty operations
Base URL: https://staging-api.loyalty.lt/api/
Authentication: API Key + Secret
  • Simple Integration: Basic loyalty card management
  • Point-of-Sale Systems: Award and redeem points at checkout
  • E-commerce Stores: Integrate with existing shopping platforms
  • Small Businesses: Quick setup without complex development

​
SDK APIs

Purpose: Advanced developer integration with enhanced features
Base URL: https://staging-api.loyalty.lt/{locale}/sdk/
Authentication: JWT Tokens + API Credentials
  • Mobile Applications: Real-time loyalty features
  • Web Applications: Advanced user interfaces
  • Custom Integrations: Tailored loyalty solutions
  • Third-party Platforms: Deep integration capabilities

​
Partner APIs

Purpose: Multi-shop management and business analytics
Base URL: https://staging-api.loyalty.lt/{locale}/partners/
Authentication: JWT Tokens (Partner Level)
  • Multi-location Businesses: Manage multiple shops
  • Franchise Operations: Centralized loyalty management
  • Analytics Dashboards: Business intelligence tools
  • White-label Solutions: Custom branded portals

​
Backend Infrastructure

​
Core Technologies

Laravel Framework

Version: 10.x
  • RESTful API architecture
  • Eloquent ORM for database operations
  • Built-in authentication and authorization
  • Queue system for background jobs

PostgreSQL Database

Version: 15.x
  • ACID compliance for data integrity
  • Advanced querying capabilities
  • JSON column support
  • Horizontal scaling support

Redis Cache

Use Cases:
  • Session storage
  • API rate limiting
  • Queue management
  • Real-time data caching

Ably WebSockets

Features:
  • Real-time point updates
  • Live game synchronization
  • Instant notifications
  • Event broadcasting

​
Database Schema

The platform uses a normalized database schema optimized for loyalty operations:

​
Frontend Applications

​
Partners Portal

Technology: Remix.js with TypeScript
URL: https://partners.loyalty.lt
  • Multi-shop dashboard
  • Analytics and reporting
  • User management
  • API credential management
  • Settings configuration

​
Website

Technology: Next.js with TypeScript
URL: https://loyalty.lt
  • Marketing and information
  • Partner onboarding
  • Documentation portal
  • Support resources

​
Email Marketing

Technology: Mautic Platform
URL: https://emails.loyalty.lt
  • Automated email campaigns
  • Customer segmentation
  • A/B testing
  • Performance tracking

​
SDK Libraries

​
JavaScript/TypeScript SDK

Package: @loyalty-lt/javascript-sdk
Features: WebSocket support, TypeScript definitions, React hooks 
import { LoyaltySDK } from '@loyalty-lt/javascript-sdk';

const sdk = new LoyaltySDK({
  apiKey: 'your_api_key',
  environment: 'staging'
});

​
React SDK

Package: @loyalty-lt/react-sdk
Features: React hooks, components, context providers 
import { useLoyaltyCard, LoyaltyProvider } from '@loyalty-lt/react-sdk';

function App() {
  return (
    <LoyaltyProvider apiKey="your_key">
      <LoyaltyCard customerId="123" />
    </LoyaltyProvider>
  );
}

​
PHP SDK

Package: loyalty-lt/php-sdk
Features: Laravel integration, Composer package, PSR-4 compliant 
use LoyaltyLT\SDK\LoyaltyClient;

$client = new LoyaltyClient([
    'api_key' => 'your_api_key',
    'api_secret' => 'your_api_secret'
]);

​
Security Architecture

​
Authentication Methods

Used by: Shop APIs, initial SDK authentication
Method: X-API-Key + X-API-Secret headers
Security: HTTPS only, credential rotation supported

​
Security Features

Rate Limiting

  • Per-endpoint limits
  • IP-based throttling
  • Token bucket algorithm
  • Custom rate limits for partners

Data Protection

  • HTTPS encryption in transit
  • Database encryption at rest
  • PII data anonymization
  • GDPR compliance features

Access Control

  • Role-based permissions
  • API scope limitations
  • IP whitelisting
  • Audit logging

Monitoring

  • Real-time error tracking
  • Performance monitoring
  • Security event logging
  • Automated alerts

​
Deployment Architecture

​
Environment Setup

URL: staging-api.loyalty.lt
Purpose: Development and testing
Features: Test data, full API access, reset capabilities

​
Infrastructure Components

​
Scalability Considerations

​
Horizontal Scaling

The platform is designed to scale horizontally across multiple servers and regions.
  • Stateless Architecture: All application servers are stateless
  • Database Sharding: Customer data can be partitioned by region
  • Cache Distribution: Redis cluster with automatic failover
  • CDN Integration: Static assets served from global CDN

​
Performance Optimization

  • Database Indexing: Optimized indexes for common queries
  • Query Caching: Frequent queries cached in Redis
  • API Response Caching: Conditional caching based on data freshness
  • Background Processing: Heavy operations moved to queue system

​
Integration Patterns

​
E-commerce Integration

1

Plugin Installation

Install platform-specific plugin (WooCommerce, Shopify, etc.)
2

API Configuration

Configure API credentials in plugin settings
3

Event Mapping

Map e-commerce events to loyalty actions (purchase → points)
4

UI Integration

Add loyalty widgets to checkout and account pages

​
Custom Application Integration

1

SDK Installation

Install appropriate SDK for your platform
2

Authentication Setup

Implement JWT authentication flow
3

WebSocket Connection

Establish real-time connection for live updates
4

Event Handling

Implement webhook endpoints for event processing

​
Next Steps

API Authentication

Learn about authentication methods and security best practices.

Shop API Reference

Explore the Shop API endpoints for basic loyalty operations.

SDK Integration

Get started with our JavaScript/TypeScript SDK.

Partner Portal

Set up multi-shop management and analytics.