Nova-Rewards

Nova Rewards

A blockchain-powered loyalty platform that lets businesses issue tokenized rewards on the Stellar network.

---

Overview

Nova Rewards replaces fragmented, opaque loyalty programs with on-chain token issuance. Merchants create reward campaigns; users earn, hold, and redeem NOVA tokens directly from a crypto wallet. Every transaction is verifiable on Stellar — no black-box points systems.

Who this repo is for:

• Developers building integrations or contributing features
• Merchants evaluating the platform or self-hosting
• Contributors looking for a starting point

---

Architecture

graph TD
    subgraph Client
        FE["Frontend\nNext.js / React PWA\n:3000"]
    end

    subgraph Backend
        BE["Backend API\nNode.js / Express\n:3001"]
        RD["Redis\nCache & Rate Limiting\n:6379"]
        PG["PostgreSQL\nPrimary Store\n:5432"]
    end

    subgraph "Stellar Network"
        SC["Soroban Smart Contracts\nnova-rewards · nova_token\nreward_pool · governance\nvesting · referral\ndistribution · admin_roles"]
        HZ["Horizon RPC"]
    end

    subgraph Infra
        GW["Nginx Gateway\n:8080"]
        MON["Prometheus + Grafana\nmonitoring/"]
    end

    FE -->|REST / WebSocket| GW
    GW --> BE
    BE --> PG
    BE --> RD
    BE -->|Stellar SDK| HZ
    HZ --> SC
    MON -.->|scrape| BE

Key directories:

Path	What lives there
novaRewards/frontend/	Next.js PWA — pages, components, stores
novaRewards/backend/	Express API — routes, services, DB repos
contracts/	Soroban smart contracts (Rust)
novaRewards/database/	SQL migrations (run in order)
monitoring/	Prometheus, Grafana, Alertmanager configs
infra/	Terraform modules (VPC, RDS, EC2, ElastiCache)
k8s/	Kubernetes manifests + Helm chart
docs/	All extended documentation

---

Tech Stack

Layer	Technology
Blockchain	Stellar
Smart Contracts	Soroban (Rust, wasm32v1-none)
Frontend	Next.js 14, React, Tailwind CSS, Zustand
Backend	Node.js 20, Express, PostgreSQL 16, Redis 7
Auth	JWT (access + refresh tokens)
Wallet	Freighter browser extension
Infra	Docker Compose, Kubernetes, Helm, Terraform
Monitoring	Prometheus, Grafana, Alertmanager
CI/CD	GitHub Actions

---

Quick Start

Gets you running locally in under 15 minutes.

Prerequisites

Tool	Version	Install
Docker Desktop	latest	docker.com
Node.js	≥ 20	nodejs.org (for running tests outside Docker)
Rust (stable)	see rust-toolchain.toml	rustup.rs (for contract development)
Freighter wallet	latest	freighter.app

1 — Clone

git clone https://github.com/barry01-hash/Nova-Rewards.git
cd Nova-Rewards

2 — Configure environment

cd novaRewards
cp .env.example .env   # fill in secrets — see Environment Setup below

3 — Start the full stack

docker compose up --build

This single command starts all services:

Service	URL	Description
Frontend	http://localhost:3000	Next.js PWA (hot reload via next dev)
Backend API	http://localhost:3001	Express API (hot reload via nodemon)
Nginx gateway	http://localhost:8080	Reverse proxy
PostgreSQL	localhost:5432	Primary database (data persisted in postgres_data volume)
Redis	localhost:6379	Cache & rate limiting (data persisted in redis_data volume)
Stellar standalone	http://localhost:8000	Local Soroban/Stellar node (RPC at /rpc)

Database migrations run automatically before the backend starts. Hot reload is active for both backend (nodemon) and frontend (Next.js dev server) — saving a file triggers an instant reload with no container restart needed.

To run only the infrastructure services (no app):

docker compose up postgres redis stellar

To stop and remove containers (volumes are preserved):

docker compose down

To also wipe persisted data:

docker compose down -v

4 — Set up Soroban contracts

./scripts/setup-soroban-dev.sh   # installs wasm32v1-none target, registers local network
./scripts/build-contracts.sh     # compiles all contracts to WASM
./scripts/test-contracts.sh      # runs contract test suite

PowerShell:

./scripts/setup-soroban-dev.ps1
./scripts/build-contracts.ps1
./scripts/test-contracts.ps1

5 — Run application tests

cd novaRewards
npm run test:backend    # Jest — backend unit + integration
npm run test:frontend   # Jest — frontend components

For disclosure policy, scope, severity, and reward tiers, see SECURITY.md.

---

Environment Setup

Copy novaRewards/.env.example to novaRewards/.env and fill in the required values:

cp novaRewards/.env.example novaRewards/.env

Required variables:

Variable	Description
ISSUER_PUBLIC / ISSUER_SECRET	Stellar issuer keypair (creates NOVA asset)
DISTRIBUTION_PUBLIC / DISTRIBUTION_SECRET	Stellar distribution keypair
STELLAR_NETWORK	testnet (dev) or mainnet (prod)
DATABASE_URL	PostgreSQL connection string
REDIS_URL	Redis connection string
JWT_SECRET	Long random string for signing JWTs
NEXT_PUBLIC_API_URL	Backend URL visible to the browser

For Vercel deployments see .env.vercel.example. For production infrastructure see infrastructure/.env.example.

Never commit .env files. They are in .gitignore.

---

Contributing

1. Find or create an issue — all work is tracked in GitHub Issues.
2. Branch off main:

   feat/<short-description>
   fix/<short-description>
   docs/<short-description>
   

3. Run checks before pushing:

   npm run lint && npm run test
   # contracts:
   cargo fmt --all && cargo clippy -- -D warnings && cargo test
   

4. Open a PR against main — fill in the PR template and link the issue.
5. Two approvals required before merge. PRs are squash-merged.

Full details: docs/pr-process.md · docs/code-style.md

---

License

This project is proprietary. All rights reserved © Nova Rewards.
See LICENSE for terms, or contact the maintainers for licensing inquiries.

---

Documentation Index

Document	Description
docs/PRD.md	Product requirements and roadmap
docs/architecture.md	Detailed system architecture
docs/system-design.md	Mermaid component, data-flow, contract interaction, and deployment topology diagrams
docs/adr/README.md	Architecture decision records for key system design choices
docs/contracts.md	Contract addresses, deploy & upgrade instructions
docs/abi-reference.md	Full ABI — function signatures, events, integration examples
docs/error-codes.md	Contract error codes and remediation
docs/api/README.md	REST API overview
docs/api/openapi.json	OpenAPI 3.0 spec
docs/deployment/guides.md	Deployment guides (Docker, K8s, Vercel)
docs/security/README.md	Security overview
docs/security/threat-model.md	Threat model
docs/security/security-best-practices.md	Security best practices
docs/stellar/integration.md	Stellar / Horizon integration guide
docs/tokenomics.md	Token economics
docs/ops/runbook.md	Operations runbook
monitoring/README.md	Monitoring stack setup
contracts/README.md	Smart contracts overview
novaRewards/README.md	App-level setup (frontend + backend)
infrastructure/README_DEVOPS_SETUP.md	DevOps / infra setup
ROADMAP.md	Issue tracker and priorities