Platform Overview

NovaBrand enables brands to create digital membership programs ("Passes") with on-chain tokens, activations, collectibles, and rewards. The platform consists of:

Key System Components

Backend (Django) — REST APIs, business logic, admin portals, Celery task dispatch. Multiple admin sites: Brand Manager, User Manager, Support, Blockchain, Config.

Frontend (React) — Single-page app deployed to S3, served via CloudFront with environment-specific subdomains (dev/staging/app).

Database (PostgreSQL + RDS) — Core data store with HStore extension. Automated RDS snapshots for backup.

Celery + Redis — Async task processing for blockchain operations (minting, airdrops, token transfers), email dispatch, and scheduled cron jobs. Workers managed via Supervisor on a dedicated EC2 instance.

Blockchain (Flow) — Smart contracts (Cadence) for NFT-based membership tokens. Brands, Passes, and Collectibles are represented on-chain. Backend interacts via flow-py-sdk.

Stripe — Payment processing with webhook integration at /api/v1/payments/webhook/.

Shopify Plugin — Embedded Shopify sales channel app (React 19 + Polaris). Enables merchants to sync products, manage orders, and link their accounts — all within the Shopify Admin.

AWS Services — EC2 (app + worker servers), RDS (PostgreSQL), S3 (static/media), Lambda (image compression, wallet verification, meta tags), CloudFront (CDN), SES (email).

Architecture Diagram

Repositories

Technical Architecture & API Reference

1. System Architecture Overview

1.1 High-Level Architecture

NovaBrand is a web platform that connects brands and consumers around digital memberships ("passes"), collectibles, incentives, and commerce. The system is split into:

1.2 Request Flow

1. User opens the app in the browser.
2. Frontend resolves the API base URL from VITE_API_BASE_URL and sends all API requests to that origin.
3. Backend serves REST endpoints under https://<backend-host>/api/v1/...
4. Authenticated requests include the header: Authorization: Token <token>.
5. Backend uses Django ORM (PostgreSQL in production, SQLite in dev), optional Redis for cache, Celery for async jobs, and integrates with S3, Stripe, Flow, Shopify, and Firebase as needed.

1.3 Deployment Context

• Frontend and backend are deployed separately (frontend on S3 + CloudFront CDN, backend on EC2 with Nginx + uWSGI).
• Celery workers run on a dedicated EC2 instance, managed via Supervisor.
• CORS, allowed hosts, and API base URL are configured per environment.

Frontend environments (automated via GitHub Actions):

Backend deployment is manual (SSH → git pull → migrate → uWSGI reload).

2. Dependency Graph

2.1 Frontend Dependencies

2.2 Backend Dependencies

3. API Endpoints

All routes below are relative to the backend base URL and the prefix /api/v1/. Unless stated otherwise, endpoints expect Authorization: Token <token> for authenticated access.

3.1 Meta Tags

3.2 Brand

3.3 Pass (Public / Consumer-Facing)

3.4 User

3.5 Activations

Activations are engagement features (polls, airdrops, claim codes, merch drops, social share) scoped by brand or pass.

3.6 Collectible (Public)

3.7 Activity

3.8 Analytics

3.9 Social Media

3.10 Payments

3.11 UGC Campaign

3.12 Shopify

Shopify webhooks (POST, by Shopify): customers/data_request, customers/redact, shop/redact, app/uninstalled, products/create, products/update, products/delete, create-order, orders/updated, orders/paid, orders/cancelled, orders/fulfilled, inventory_items/update, collections/create, collections/update, collections/delete.

3.13 Support & Utilities

4. Authentication Patterns

4.1 Backend Auth

• Token: rest_framework.authentication.TokenAuthentication — Header: Authorization: Token <token>
• Session: SessionAuthentication (browser/admin)
• Basic: BasicAuthentication (tooling)
• Default permission: IsAuthenticated for most API views. Specific views override to AllowAny.
• Object-level: django-guardian for brand/pass-level checks.

4.2 Frontend Auth

• Token stored in localStorage
• utils/ApiHelpers.ts → getAuthHeaders() adds Authorization: Token <token> to all Axios requests
• UserContext holds token, userDetails, and isUserLoggedIn
• Routes wrapped in AuthenticatedRoute require login; BrandRoute enforces brand-admin access

4.3 Auth Flow Summary

5. Inter-App Relationships

5.1 Frontend ↔ Backend

• Single client: One SPA talks to one backend via VITE_API_BASE_URL.
• All server state via API: No direct DB or cache access from the frontend.
• Errors: Backend returns structured error payloads; frontend uses utils/request.ts and ApiHelpers.buildErrorMessage().

5.2 Backend ↔ External Systems

5.3 Data Ownership

• Brands are owned by users (brand admin). Passes belong to brands. Releases belong to passes.
• Activations (polls, airdrops, claim codes, merch, social share) are scoped to brands/passes.
• User inventory (purchased/claimed passes) is stored and returned by the backend.
• UGC campaigns are brand-owned; submissions are linked to campaigns and users.
• Shopify data (products, orders) is tied to brand and shop.

Database Schema Documentation

Django 3.2.8 PostgreSQL 11 Apps ~45 Models

Overview

The platform uses PostgreSQL as its primary database, accessed through Django 3.2.8 ORM. The schema spans 11 Django applications containing approximately 45 models. The database uses the HSTORE extension and supports both standard auto-increment integer primary keys and ShortUUID primary keys for certain models.

Base Model Classes

• BaseModelWithCreatedInfo: Adds created_at (auto) and created_by (FK to User)
• BaseModelWithCreatedInfoUUID: Same as above + ShortUUID primary key
• BaseImageModel: Adds image_file, image_url, image_hash, and original/small/medium URL variants
• BaseProfileCoverImageModel: Adds profile_image, cover_image with URLs and hashes

App-to-Model Summary

Core Models

Brand App

The brand app contains the largest models, managing brands, passes (NFT collections), releases, tokens, events, UGC campaigns, Shopify integrations, and subscriptions.

Key Models

• Tags: Tagging system for brands (symbol auto-uppercased, spaces replaced with underscores)
• Brand: Core entity with approval workflow, Stripe/Shopify connections, profile/cover images
• Pass: NFT collections with unique_together constraint on (brand, name)
• PassReleases: Sale/release windows with pricing and time windows
• PassReleaseWhitelist: Whitelisted emails for restricted releases
• PlatformToken: Individual NFT tokens with minting and claiming tracking
• PassBenefits: Benefits associated with pass ownership
• PassEvents: Events linked to pass releases
• PassClaims: Pass claim requests by users
• SubscriptionDetails: Subscription pricing management
• StoreFrontListing: Secondary market listings
• BlockchainTransaction: Audit log for blockchain operations
• UGCCampaign: User-generated content campaigns
• UGCCampaignSubmission: Individual UGC submissions
• BrandInvitation: Brand collaboration invitations (token-based, 48-hour expiry)
• ConnectedStore: Shopify store connections
• Product, ProductVariant, ProductImage: Shopify product sync
• ShopifyOrder: Shopify order webhook data

User Management App

• UserProfile: Extended user profile (1:1 with auth.User), stores wallet, social links, address
• UserInventory: Tracks items owned by users (passes/collectibles), uses GenericForeignKey
• Achievements: Gamification badges
• UserOTPMapping: Email OTP verification (30-min expiry)
• NonceSignatureTracker: Wallet proof nonce/signature pairs

Activations App

• Activations: Master activation type registry
• BrandActivations: Junction table linking Brands to unlocked Activations
• Collectible: Core engagement entity
• CollectibleDrop: Individual collectible deliveries to users
• PassDrop: Pass airdrops
• RaffleDrop: Raffle-based distributions

Payments & Orders

• PaymentRecord: Stripe payment records
• PurchaseOrder: Completed pass purchases
• PassLockTable: Temporary 5-minute lock during purchase

Status Enumerations

Activation Types

airdrop merch_drop claim_code poll social_share ugc_submission

Key Relationship Map

Core Hierarchy

Engagement Chain

Commerce Chain

User Chain

Implementation Notes

• Soft Deletes: Most models use is_deleted BooleanField rather than actual deletion. Custom managers filter out deleted records by default.
• GenericForeignKeys: Used extensively in Activity, Notifications, UserInventory via content_type + object_id pairs.
• Time Representation: Many models store both epoch milliseconds and Django DateTimeFields for blockchain and Django admin compatibility.
• UUID Primary Keys: ShortUUID (22-char) primary keys used in Brand, Pass, Collectible, PaymentRecord, UGCCampaign, etc.
• Image Processing: Models inheriting BaseImageModel automatically generate image hashes and trigger AWS Lambda for image resizing.
• Signals: Several post_save signals exist for UserInventory verification, BrandInvitation permissions, retroactive incentive drops, and cache invalidation.
• DO_NOTHING ForeignKeys: Many FK relationships use on_delete=DO_NOTHING for audit trail preservation.

Celery Tasks & Cron Jobs Guide

Overview

The platform uses Celery (v5.2.7) with Redis as the message broker to handle asynchronous tasks. The system processes blockchain transactions, email notifications, subscription management, UGC campaign lifecycle events, and media file operations outside the HTTP request-response cycle.

Task Summary

Cron Jobs (Celery Beat)

Celery Beat schedules are stored in the Django database via django-celery-beat. Currently, only 2 crons are active in production.

How to Enable a Commented Cron

1. SSH into the EC2 instance and navigate to the backend app directory.
2. Open Django shell: python manage.py shell
3. Import and call the setup function for the desired cron.
4. Verify in Django Admin > Periodic Tasks that the new cron appears.
5. Restart Celery Beat: sudo supervisorctl restart celerybeat

Detailed Task Reference

blockchain_transaction

Parameters: type (str) — one of 13 sub-types; payload (dict, optional)

Central dispatcher for all blockchain operations on Flow. Uses a match/case statement to route to the appropriate worker function. Each worker runs asynchronously via asyncio.run() and gets a proposer address based on the worker hostname (round-robin across workers).

Blockchain Transaction Sub-Types

make_latest_subscription_details_active

Cron: Daily at 00:00 UTC — External Dependencies: Stripe API

Activates subscription plan changes scheduled for the current date. Deactivates old subscription details, activates new ones, and modifies Stripe subscription schedules to reflect pricing/interval changes. Uses atomic database transactions. Creates prorated transition phases in Stripe when payment cycles change.

create_and_send_zip_email

Parameters: media_urls (list of S3 URLs), recipient_email (str)

Downloads media files from S3, compresses them into a ZIP archive in memory, uploads the ZIP back to S3, generates a presigned download URL (valid for 2 days), and emails the link to the recipient. Schedules cleanup_temp_zip_file to run 48 hours later.

manage_product_publication

Parameters: store_id, product_ids (list), action ('publish' or 'unpublish')

Publishes or unpublishes products on a Shopify store via the GraphQL Admin API. Processes products concurrently using ThreadPoolExecutor with max 5 workers. Each product has its own retry logic (3 attempts with exponential backoff).

Supervisor Configuration

All Celery processes are managed by Supervisor on the production EC2 instance.

Key Configuration Details

• Each worker runs with concurrency=1 (single thread per worker). Intentional because blockchain transactions are async and must be isolated.
• Workers are named wrkr_1, wrkr_2, wrkr_3. The blockchain_transaction task uses this hostname to determine which Flow proposer address to use.
• Beat runs as a single process with a 10-second startsecs delay. Uses the Django database scheduler.
• All processes run as the ubuntu user and auto-restart on failure.

Common Supervisor Commands

# Check all process status
sudo supervisorctl status

# Restart all Celery workers
sudo supervisorctl restart celery-workers:*

# Restart Beat scheduler
sudo supervisorctl restart celerybeat

# Restart a single worker
sudo supervisorctl restart celery-worker-1

# View worker logs (live)
tail -f /var/log/platform_celeryd1.log

# View Beat logs (live)
tail -f /var/log/platform_beat.log

AWS Operations Runbook

Production Environment

Region: us-east-1

EC2 Instances

Application Servers

Worker Servers (Celery)

SSH Access

1. Log in to the AWS Console
2. Navigate to EC2 → Instances
3. Select the instance
4. Click Connect → EC2 Instance Connect

Application Reload (Without Restarting Server)

touch ~/backend/deployment/uwsgi.ini

Restart Nginx (If Required)

sudo systemctl restart nginx

Restart Celery Workers

sudo supervisorctl restart all

RDS – PostgreSQL Database

Health Checks

AWS Console → RDS → Databases → Select DB Instance. Verify: Status, CPU Utilization, Active Connections, Storage Utilization.

Create Manual Snapshot

1. RDS → Snapshots
2. Click Create Snapshot
3. Select Database
4. Provide Snapshot Name

Amazon S3 – Storage

AWS Lambda Functions

First-Time Server Setup

Nginx

sudo apt-get install nginx -y
sudo mkdir -p /var/www/platform/{media,static}
sudo chown -R ubuntu:www-data /var/www/platform
sudo chmod -R 770 /var/www/platform
python manage.py collectstatic
sudo ln -s ~/backend/deployment/nginx.conf /etc/nginx/sites-enabled/backend
sudo service nginx reload

uWSGI

sudo pip3 install uwsgi
sudo mkdir -p /etc/uwsgi/vassals
sudo ln -s ~/backend/deployment/uwsgi.ini /etc/uwsgi/vassals/backend_uwsgi.ini
# Test: uwsgi --emperor /etc/uwsgi/vassals --uid www-data --gid www-data
# For auto-start, add to /etc/rc.local:
/usr/local/bin/uwsgi --emperor /etc/uwsgi/vassals --uid www-data --gid www-data --daemonize /var/log/uwsgi-emperor.log

SSL (Certbot / LetsEncrypt)

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d <your-sub-domain>
sudo service nginx restart

# Renew: certbot renew
# Dry run: certbot renew --dry-run

Celery Workers (Supervisor)

# 1. Install supervisor
sudo apt-get install supervisor

# 2. Create log files
sudo touch /var/log/platform_celeryd{1,2,3}.log /var/log/platform_beat.log
sudo chown ubuntu:www-data /var/log/platform_celeryd{1,2,3}.log /var/log/platform_beat.log

# 3. Create softlinks to supervisor config
sudo ln -s ~/backend/supervisor_conf/celery.conf /etc/supervisor/conf.d/celery.conf
sudo ln -s ~/backend/supervisor_conf/celery_beat.conf /etc/supervisor/conf.d/celery_beat.conf

# 4. Reload supervisor
sudo supervisorctl reread
sudo supervisorctl update

# 5. Manage workers
sudo supervisorctl start celery-workers:*
sudo supervisorctl status
sudo supervisorctl restart all

Rollback Procedure

1. git checkout <previous_commit_or_tag>
2. Run migrations if needed: python3 manage.py migrate
3. Reload uWSGI: touch ~/backend/deployment/uwsgi.ini
4. Restart Celery: sudo supervisorctl restart all

Troubleshooting

Python 3.10 Upgrade

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.10 python3.10-dev python3.10-distutils build-essential
python3.10 -m pip install --upgrade pip
pip install uwsgi

Common issues after upgrade:

• uWSGI using old Python: Use /usr/local/bin/uwsgi (full path) in /etc/rc.local
• Celery using old Python: Edit celery shebang to #!/usr/bin/python3.10

Operations Checklist

macOS Local Development Setup

PostgreSQL Installation

Step 1: Check if PostgreSQL Is Installed

psql --version

If you see a version number, skip ahead. If command not found: psql, proceed below.

Step 2: Install Homebrew (If Not Already Installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 3: Install PostgreSQL

brew install postgresql@18
psql --version

Fix: PATH Not Set

If psql is still not found after installation, add it to your PATH:

echo 'export PATH="/opt/homebrew/opt/postgresql@18/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
psql --version

Database Setup

Create Database and User

sudo -u postgres -i psql

CREATE DATABASE platform_db;
CREATE USER platform_user WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE platform_db TO platform_user;
CREATE EXTENSION hstore;
GRANT USAGE ON SCHEMA public TO platform_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO platform_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO platform_user;
CREATE EXTENSION IF NOT EXISTS vector;

Restore Database Dump

# Step 1: Drop existing database
psql -U postgres -h localhost -p 5432 -d postgres -c "DROP DATABASE IF EXISTS platform_db;"

# Step 2: Recreate with correct owner
psql -U postgres -h localhost -p 5432 -d postgres -c "CREATE DATABASE platform_db OWNER platform_user;"

# Step 3: Ensure schema ownership
psql -U postgres -h localhost -p 5432 -d platform_db -c "ALTER SCHEMA public OWNER TO platform_user;"
psql -U postgres -h localhost -p 5432 -d platform_db -c "GRANT ALL ON SCHEMA public TO platform_user;"

# Step 4: Restore dump
PGPASSWORD=password pg_restore \
  -U platform_user \
  -d platform_db \
  -h localhost \
  -p 5432 \
  --no-owner \
  --no-privileges \
  ~/Downloads/platform_db_dump.dump

Python 3.10.8 Setup

# Install Python 3.10
brew install [email protected]

# Verify
python3.10 --version
# Expected: Python 3.10.8

Backend Requirements Installation

# Install ffmpeg globally
brew install ffmpeg

# Required files (place in project):
# requirements.txt        -> <project_path>/requirements.txt
# firebase_creds.json     -> <project_path>/app/platform/firebase_creds.json
# local_settings.py       -> <project_path>/app/platform/local_settings.py
# setup_venv.sh           -> <project_path>/scripts/setup_venv.sh

# Give file running permissions
chmod +x ./scripts/setup_venv.sh

# Run migrations (inside app directory)
python3 manage.py migrate

If Permission Issues on Migrations

GRANT USAGE ON SCHEMA public TO platform_user;
GRANT CREATE ON SCHEMA public TO platform_user;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO platform_user;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO platform_user;

Create Log Files

cd /var/log/
sudo touch platform-web2.log platform-web3.log platform-cron.log
sudo chown <user> platform-web2.log platform-web3.log platform-cron.log

Shopify Plugin Guide

Overview

The Shopify plugin is an embedded Shopify sales channel app that allows merchants to connect their Shopify stores with the NovaBrand marketplace. It handles product synchronization, order management, and account linking — all within the Shopify Admin interface.

Tech Stack

React 19 TypeScript Vite 7 Shopify Polaris v13 App Bridge v3 Apollo Client S3 + CloudFront

Architecture

Key Flow

1. Installation: Merchant installs from Shopify → backend handles OAuth at /api/v1/shopify/connect/ → redirects to Shopify permission screen → callback at /api/v1/shopify/callback/
2. Account Linking: After OAuth, merchant connects their NovaBrand account via a popup to the dashboard
3. Embedded App: Once connected, the app runs inside Shopify Admin with host + shop URL params, using App Bridge for auth context

App Tabs

Backend Integration

Webhooks

App Configuration

• API Version: 2025-04
• Embedded: Yes
• POS: No

Required Scopes

read_customers, read_orders, write_orders, read_products, read_publications, write_publications, write_resource_feedbacks, write_script_tags, unauthenticated_write_checkouts, unauthenticated_read_checkouts

Development Setup

git clone [email protected]:org/novabrand-shopify.git
cd novabrand-shopify
yarn install
cp env.example .env    # fill in your Shopify API key
yarn dev               # starts at http://localhost:3000

Environment Variables

Deployment

Both use env-cmd to load .env, build with Vite, upload to S3, and invalidate CloudFront cache.

Billing