Revision History

Date	Version	Reason for Issue	Author
27.11.24	1.0.0	Initial Version	Derek Counihan

1. Introduction

This document provides a comprehensive overview of the Nudj Platform’s system architecture and integration specifications. It is intended for technical teams implementing Nudj’s loyalty and engagement features into their existing systems.

1.1 Platform Overview

Nudj is a web-based, white-label solution designed to create engaging digital experiences for brands. The platform supports: - Points-based reward systems - Social engagement tracking - Community management - Real-time analytics - Custom reward programs

1.2 Integration Methods

The platform supports three primary integration methods: 1. REST APIs 2. Webhooks 3. SDK Implementation (coming soon)

2. System Architecture

2.1 Technical Stack

Core Infrastructure

Hosting Platform: Vercel

Global edge network for high availability

Built-in resilience and scaling

Automated deployments via GitHub Actions

Multiple environments (Development, Staging, Production)

Technology Stack

The Nudj platform is built using modern cloud-native technologies:

Frontend Layer

NextJS 15 application framework

TypeScript for type safety

ShadCN and Tailwind CSS for UI components

Responsive web and mobile interfaces

Embeddable widget support

API Layer

tRPC for type-safe API routes

OpenAPI compliant endpoints

Zod & Class Validator for schema validation

Real-time WebSocket connections

Data Layer

MongoDB Atlas for primary data storage

Self-managed encryption keys

Secure key management system

Data replication and backups

DevOps & Deployment

GitHub for version control

GitHub Actions for CI/CD pipeline

Automated testing and verification

Zero-downtime deployments

System Architecture Diagram

2.2 Infrastructure

Hosting Environment

Platform: Vercel

Environments:

Development

Staging

Production

Benefits:

Global edge network

High availability

Built-in resilience

Deployment

CI/CD Pipeline: GitHub Actions

Deployment Platform: Vercel

Process:

Code push to GitHub

Automated testing

Build verification

Deployment to appropriate environment

2.3 Platform Structure Hierarchy

The following diagram illustrates the hierarchical structure of the Nudj platform, using Netflix and Game of Thrones as an example:

This hierarchical structure demonstrates: - Organization level (Netflix) - Community level (Game of Thrones) - Main features (Campaigns, Missions, Reward Store, Posts, Leaderboard) - Detailed breakdown of each feature branch - Reward types and requirements

The diagram provides a clear overview of how different components relate to each other within the Nudj platform structure.

3. Core User Journey Flows

3.1 Challenge System

The Challenge System enables organizations to create engaging, interactive experiences that drive user participation and reward completion.

For detailed implementation guides, see: - Creating Engaging Challenges on Nudj - Setting up Challenges with Actions

Challenge Structure

Challenge Components

Title and description

Visual elements (banner, logo)

Time constraints (start/end dates)

Reward configuration

Action sequence

Challenge Types

Sequential challenges (ordered actions)

Flexible challenges (any order)

Time-limited challenges

Recurring challenges

Featured challenges

Challenge Settings

Visibility controls

Access requirements

Time restrictions

Point rewards

Completion criteria

Action Configuration

Action Types

Multiple Choice Questions

Open Text Responses

File Uploads

Social Media Actions

Custom Integrations

Learn more: Available Action Types

Action Properties

Required vs Optional

Time limits

Retry attempts

Point values

Success criteria

Action Flow

Sequential progression

Skip options for optional actions

Validation rules

Feedback mechanisms

Progress tracking

Engagement Features

User Experience

Progress indicators

Real-time feedback

Point accumulation

Achievement tracking

Completion celebrations

Gamification Elements

Points and rewards

Achievement badges

Progress milestones

Leaderboards

Time-based bonuses

Learn more: Implementing Gamification

Social Features

Share achievements

Community engagement

Social proof elements

Group challenges

Collaborative goals

Challenge Management

Administrative Tools

Challenge creation wizard

Action sequence builder

Preview functionality

Bulk operations

Analytics dashboard (coming soon)

Monitoring Features

Participation tracking

Completion rates

User progress

Point distribution

Engagement metrics

Advanced Analytics (PowerBI)

Challenge and Reward Flow

The following diagram shows how users interact with challenges and earn rewards. Here’s what happens:

Discovery and Start - Users browse available challenges in the app - Each challenge shows clear requirements and potential rewards - Users can start challenges that interest them - The system tracks which challenges are active

Participation - As users perform actions, the system automatically tracks their progress - They can see real-time updates on how close they are to completion - The app sends encouraging notifications at key milestones - Users can pause and resume challenges at any time

Completion and Rewards - When all requirements are met, the challenge auto-completes - Users receive instant notification of their success - Points and rewards are automatically added to their account - Rewards are displayed in their profile/wallet

This flow demonstrates: - Client App Responsibilities: - Display challenges and progress - Send user activities to Nudj - Show notifications and celebrations

Nudj Platform Handles:

Challenge configuration and management

Progress tracking and calculations

Completion validation

Reward processing and distribution

Data storage and security

The integration is designed to be simple - your app just needs to display information and send activities, while Nudj manages all the complex logic behind the scenes.

3.2 Points and Rewards Engine

In-Game Currency System

The platform implements a customizable in-game currency system that drives user engagement and rewards participation.

For detailed information, see: - Understanding In-Game Currency on Nudj

Currency Configuration

Customizable currency name and branding

Configurable earning rules and rates

Flexible spending mechanisms

Point-to-value conversion rates

Balance Management

Real-time balance tracking

Transaction history

Points expiration rules

Balance reconciliation

Audit logging

Points Engine Features

Earning Rules

Challenge completion rewards

Mission-based earnings

Engagement bonuses

Milestone rewards

Special event multipliers

Spending Options

Sweepstakes entries

Exclusive content access

Event participation

Physical/digital rewards

Special experiences

Transaction Processing

Real-time point calculations

Multiplier application

Bonus point rules

Expiration tracking

Available vs. pending points

Balance Management

Current balance tracking

Pending points tracking

Expiring points monitoring

Lifetime earnings tracking

Transaction history

Administrative Features

Currency Configuration

Currency name and branding

Exchange rates

Earning rules

Expiration policies

Reporting

Point distribution metrics

User engagement analytics

Spending pattern analysis

System health monitoring

Management Tools

Manual point adjustments

Bulk operations

Error correction

Audit trails

3.3 Reward Store + eWallet Service

The platform provides a comprehensive reward management system that enables organizations to create, manage, and distribute various types of rewards to users.

For detailed information, see: - Curating Perfect Rewards on Nudj - Setting Up Rewards on Nudj

Reward Types and Management

Digital Rewards

Instant delivery codes

Digital content access

Platform features/upgrades

Virtual items and collectibles

Subscription services

Physical Rewards

Merchandise and products

Custom branded items

Limited edition collectibles

Experience-based rewards

Gift cards and vouchers

Reward Configuration

Point cost settings

Availability windows

Stock management

Distribution rules

Redemption limits

Distribution Controls

Automated delivery

Manual approval workflows

Batch processing

User eligibility rules

Reward Store Features

Store Management

Category organization

Featured items

Limited-time offers

Bundle creation

Inventory tracking

User Experience

Reward discovery

Point balance display

Purchase history

Wishlist functionality

Redemption status

Administrative Tools

Reward creation wizard

Inventory management

Analytics dashboard

User purchase history

Redemption tracking

Redemption Process

Code-Based Rewards

Unique code generation

Secure delivery system

Code validation

Usage tracking

Expiration management

Rich-Text Rewards

Detailed instructions

Supporting documentation

Contact information

Redemption deadlines

Status updates

Reward Flow Diagrams

Reward Purchase Flow

When a user wants to spend their points on a reward, the process is straightforward: - First, they browse the reward store to see what’s available - When they find something they like, the system automatically checks if they have enough points - If they have sufficient points, the purchase is processed instantly - The reward is immediately added to their digital wallet - They receive a confirmation of their purchase

Reward Redemption Flow

Once a user has rewards in their wallet, the redemption process adapts to the reward type: - They open their digital wallet to view their available rewards - Select the reward they want to redeem - If additional information is needed (like shipping address or t-shirt size), a simple form appears - The system securely collects and stores these details - Once all required information is provided, the reward is unlocked - For physical items, fulfillment begins automatically with the provided details

This demonstrates: - Client Application Responsibilities: - Display reward catalog - Show user interface elements - Handle user interactions

Nudj Platform Handles:

Points balance management

Transaction processing

Digital wallet management

Form collection and validation

Reward fulfillment coordination

Data security and storage

Fulfillment Options:

Automated webhook integration with:

Shopify for e-commerce fulfillment

SAP for enterprise resource planning

Custom ERP systems

Third-party logistics providers

Manual processing via:

CSV exports for bulk processing

Admin dashboard downloads

Scheduled exports

The integration is streamlined - your application focuses on the user interface while Nudj manages all the complex business logic, security, and data management. Fulfillment can be automated or manual depending on your existing systems and preferences.

3.4 Missions and Achievements

The platform provides a flexible system for creating and managing missions (custom achievements) and pre-set achievements to drive user engagement and progression. Achievements in Nudj recognize long-term milestones and cumulative progress, while missions focus on short-term goals and specific tasks that keep users engaged with the app on a regular basis.

For detailed information, see: - Missions vs Achievements on Nudj - Setting Up Missions and Pre-set Achievements

Achievement System Overview

The platform includes a default set of achievements enabled for all new organizations to enhance user retention and engagement. Achievements can be configured with various parameters:

Time Periods

Daily

Weekly

Monthly

Yearly

Open-ended

Completion Logic

Stackable levels

Repeatable achievements

Period-based resets

Progressive rewards

Completion tracking

Measurement Criteria

XP gained

Challenges completed

Community visits

Actions performed

Rewards redeemed

Custom events (e.g. “User purchased item”, “User checked in to a location”)

Real-World Example: “Shopping Spree Star”

This example demonstrates how to set up a multi-level shopping achievement using the Nudj CMS:

Achievement Setup in CMS

Basic Configuration

Name: “Shopping Spree Star”

Description: “Become a shopping legend by redeeming coupons across different stores”

Category: Shopping

Time Frame: Monthly

Tracking Type: Unique Store Visits

Level Configuration Level 1: “Savvy Shopper”

Rewards:

50 points

Bronze Shopper Badge

Level 2: “Shopping Expert”

Requirement: Visit 25 different stores

Rewards:

150 points

Silver Shopper Badge

Requirement: Visit 50 different stores

Level 3: “Shopping Legend”

Rewards:

500 points

Gold Shopper Badge

Exclusive Store Access

How It Works

Day 1: User Discovery

Users see the achievement in their app

Progress shows 0/10 stores visited

All reward levels are visible

Day 3: First Steps

User visits first store and redeems a coupon

Progress automatically updates to 1/10

App sends encouraging notification

Day 15: First Milestone

User reaches 10 different stores

System automatically:

Awards “Savvy Shopper” badge

Adds 50 points to balance

Updates progress toward next level

Day 30: Ongoing Engagement

Progress reaches 15 stores

System sends motivation: “60% to Shopping Expert!”

User can share their badge on social media

Benefits

For Users

Clear progression path

Multiple reward types

Regular encouragement

Shareable achievements

For Business

Increased store visits

Higher coupon usage

Better user retention

Social media presence

Achievement Journey Flow Diagram

The following diagram illustrates the user journey for discovering, progressing through, and completing achievements.

This demonstrates: - Client Application Responsibilities: - Display achievement list and progress - Show notifications and celebrations - Send user activities to Nudj - Present rewards to users

Nudj Platform Handles:

Achievement configuration and rules

Progress tracking across all activities

Real-time event processing

Milestone calculations

Achievement validation

Reward distribution

Data persistence and security

The integration is straightforward - your application handles the user interface while Nudj manages all the complex achievement logic, progress tracking, and reward processing automatically in the background.

4. Glossary of Terms

Core Concepts - Challenge: Time-bound activities users complete for rewards - Mission: Short-term goals with immediate rewards - Achievement: Long-term milestones with progressive rewards - Points: In-game currency earned through participation - Reward: Physical or digital items purchasable with points

Technical Terms - Webhook: HTTP callback for real-time event notifications - API: Application Programming Interface for system integration - SDK: Software Development Kit for client implementation - JWT: JSON Web Token for secure authentication - OAuth: Open standard for secure authorization

Platform Components - Event Tracker: System for monitoring user activities - Points Engine: Manages point calculations and balances - Reward System: Handles reward distribution and fulfillment - eWallet: Digital storage for user rewards and points

Nudj Platform System Specifications