Admin Guide - Renewed Renaissance

🔐 Access Your Dashboard

🟢 Production Admin

www.renewed-renaissance.com/admin

🟡 Staging Admin

stage.renewed-renaissance.com/admin

🔑 Login Information

Contact your system administrator for login credentials.

⚠️ Security Notice: Never share your credentials. Use strong, unique passwords.

📦 Product Management

Adding New Products

1 Navigate to Products

Click "Products" in the left sidebar → "Add Product"

2 Enter Product Details

Name: Clear, descriptive product title
Description: Detailed product information (supports rich text)
Category: Select appropriate category (Vintage, Renaissance, etc.)
Product Type: Define attributes (size, color, material)

3 Upload Images

Add high-quality images (recommended: 1200x1200px minimum)

First image becomes the main product photo
Drag to reorder images
Add alt text for accessibility

4 Set Pricing & Inventory

Base Price: Regular selling price
Compare at Price: Original price (for showing discounts)
SKU: Stock keeping unit (unique identifier)
Inventory: Track quantity, set low stock alerts

5 Configure Variants

For products with multiple options (sizes, colors):

Add variant attributes
Set individual pricing and SKUs
Track inventory per variant

6 Publish Product

Set visibility, publication date, and channel availability

💡 Pro Tip: Use the staging environment to test new products before publishing to production!

�️ Command-Line Product Management

For bulk operations and automation, use the CLI scripts located in src/scripts/:

Available Scripts

Script	Purpose
`add_product.py`	Add single products via GraphQL API
`manage_products.py`	Manage products via Django shell (list, fix pricing, update stock)
`import_products.py`	Bulk import products from a directory

Prerequisites

1 Install Dependencies

pip install requests pyyaml

2 Navigate to Scripts Directory

cd src/scripts/

Adding Products via CLI

1 Add default sample product

python add_product.py --env dev

2 Add product from markdown file

python add_product.py --env prod --product-file products/eternal-flight-origami-crane.md

Managing Existing Products

List all products

python manage_products.py --env prod --action list

Fix variant pricing

python manage_products.py --env prod --action fix-pricing --sku "Ete/pri/4in" --price 85.00

Update stock quantity

python manage_products.py --env prod --action update-stock --sku "Ete/pri/4in" --quantity 25

Add variant to existing product

python manage_products.py --env prod --action add-variant --product-slug eternal-flight-handcrafted-origami-crane-print --sku "NEW-SKU" --price 99.00

Bulk Import Products

Import all products from directory

python import_products.py --env dev --source-dir ./products/

Dry run (preview without changes)

python import_products.py --env prod --source-dir ./products/ --dry-run

Environment Configuration

Environment	API URL	Public URL
dev	localhost:10080	dev.renewed-renaissance.com
stage	localhost:9080	stage.renewed-renaissance.com
prod	localhost:8080	www.renewed-renaissance.com

Product Markdown Format

Products can be defined in markdown files with YAML frontmatter:

---
name: "Product Name"
sku: "SKU-123"
description: "Product description..."
regular_price: "100"
sale_price: "80"
stock_status: "instock"
categories: "art > prints"
---

Product body text (used if description not in frontmatter)

Sample Products Included

products/eternal-flight-origami-crane.md - Origami crane print ($80)
products/elegant-bloom-dahlia.md - Dahlia flower print ($180)
products/ethereal-drift-jellyfish.md - Jellyfish print ($90)

⚠️ Recommended Workflow:

Test product addition in dev environment first
Validate in stage environment
Deploy to prod when ready

�📋 Order Management

Processing Orders

Order Status	Action Required	Next Step
Unfulfilled	Review order details	Create fulfillment → Mark items as fulfilled
Partially Fulfilled	Complete remaining items	Fulfill remaining products
Fulfilled	Ship products	Add tracking number → Notify customer
Returned	Process refund	Inspect items → Issue refund/credit

Fulfillment Workflow

1 Open Order

Navigate to Orders → Click order number

2 Verify Payment

Confirm payment status is "Paid" or "Authorized"

3 Create Fulfillment

Click "Fulfill" → Select items to ship → Save

4 Add Tracking

Enter carrier and tracking number → Customer receives email automatically

5 Mark as Sent

Update fulfillment status when package is shipped

👥 Customer Management

Customer Information

View and manage customer accounts:

Customer List: View all registered customers
Order History: See all orders per customer
Contact Info: Email, phone, shipping addresses
Customer Notes: Add internal notes about customers

Creating Customer Accounts

1 Navigate to Customers → Add Customer

2 Enter customer details (email required)

3 Optionally send welcome email with login instructions

Customer Groups

Segment customers for targeted marketing:

VIP customers (high value)
Wholesale buyers
Newsletter subscribers
First-time buyers

💰 Discounts & Promotions

Creating Discount Codes

1 Navigate to Discounts

Click "Discounts" → "Create Voucher"

2 Set Discount Details

Code: Customer-facing code (e.g., SUMMER25)
Type: Percentage, Fixed amount, or Free shipping
Value: Discount amount

3 Set Conditions

Minimum purchase amount
Specific products/categories
Customer eligibility
Usage limits (per customer or total)

4 Schedule Promotion

Set start and end dates/times

Sales & Promotions

Create automatic sales that apply to products:

Category Sales: Discount entire categories
Product Sales: Mark specific products on sale
Channel Sales: Different prices per sales channel

📊 Analytics & Reports

Available Reports

Report Type	What It Shows	Use Case
Sales Overview	Revenue, orders, average order value	Daily performance tracking
Product Performance	Best sellers, slow movers	Inventory planning
Customer Analytics	New vs returning customers	Marketing effectiveness
Traffic Sources	Where customers come from	Marketing ROI

Key Metrics to Monitor

Conversion Rate: Visitors who make purchases
Average Order Value (AOV): Revenue per order
Cart Abandonment: Incomplete checkouts
Customer Lifetime Value (CLV): Total customer spending
Inventory Turnover: How quickly stock sells

⚙️ Settings & Configuration

Store Settings

General: Store name, contact info, timezone
Channels: Configure sales channels (web, mobile, etc.)
Taxes: Tax rates, tax-exempt products
Shipping: Shipping zones, rates, methods

Payment Configuration

Configure payment gateways:

Stripe (credit cards, digital wallets)
PayPal
Manual payment methods (bank transfer, etc.)

Email Templates

Customize automated emails:

Order confirmation
Shipping notification
Order cancellation
Account confirmation
Password reset

🔧 Common Tasks Quick Reference

Task	Navigation Path
Add new product	Products → Add Product
Process refund	Orders → [Order] → Refund
Create discount code	Discounts → Create Voucher
Add customer	Customers → Add Customer
View sales report	Analytics → Sales
Update inventory	Products → [Product] → Variants
Configure shipping	Configuration → Shipping
Manage taxes	Configuration → Taxes

🆘 Troubleshooting

Common Issues & Solutions

Issue: Can't log in to dashboard

Verify you're using the correct environment URL
Check caps lock is off
Try password reset if needed
Clear browser cache and cookies

Issue: Product not appearing on storefront

Check product is published (not draft)
Verify channel assignment
Ensure product has available inventory
Check publication date hasn't passed

Issue: Customer not receiving emails

Verify email address is correct
Check spam/junk folders
Confirm email notifications are enabled
Test with different email address

Issue: Discount code not working

Check code is active (dates correct)
Verify minimum purchase requirements met
Ensure usage limit not exceeded
Confirm products are eligible

📞 Support Resources

Need Help?

Developer Support: See Developer Documentation
System Status: Check infrastructure health on main dashboard
GraphQL API: Test queries at /graphql endpoint

⚠️ Before Making Changes in Production

Always test changes in staging environment first
Back up data before bulk operations
Schedule major changes during low-traffic periods
Communicate changes to your team

🚀 Deployment Pipeline & Promotion

Changes flow through three environments: Dev → Stage → Production. Each promotion includes automated testing to ensure quality.

🌐 Environment Overview

Environment	URL	Purpose	Port
🟢 Development	dev.renewed-renaissance.com	Testing new features, integration testing	10080
🟡 Staging	stage.renewed-renaissance.com	Pre-production validation, acceptance testing	9080
🔴 Production	www.renewed-renaissance.com	Live customer-facing site	8080

📋 Promotion Process

1 Deploy to Development

From the project root directory:

cd deploy/01_dev
docker compose up -d --build

2 Run Integration Tests (Dev)

Verify the deployment with automated tests:

cd /path/to/renewed-renaissance-saleor
npx vitest run --config vitest.integration.config.ts tests/integration/dev.test.ts

✅ Expected: All 9 tests should pass (API health, products, categories, storefront)

3 Promote to Staging

After dev tests pass:

cd deploy/02_stage
docker compose up -d --build

4 Run Integration Tests (Stage)

npx vitest run --config vitest.integration.config.ts tests/integration/stage.test.ts

5 Run Acceptance Tests (Stage)

Full user journey and performance validation:

npx vitest run --config vitest.integration.config.ts tests/acceptance/stage.test.ts

✅ Expected: 8 acceptance tests covering browsing, checkout, performance, and security

6 Run DAST Security Scan (Stage) ⚠️ REQUIRED

Before promoting to production, run a security scan:

# Pull ZAP scanner (first time only)
docker pull ghcr.io/zaproxy/zaproxy:stable

# Run ZAP baseline scan
docker run --rm \
  -v $(pwd)/security-reports:/zap/wrk:rw \
  -t ghcr.io/zaproxy/zaproxy:stable \
  zap-baseline.py \
  -t https://stage.renewed-renaissance.com \
  -r zap-report.html \
  -J zap-report.json \
  -I

⚠️ GATE: Must show 0 FAIL results to proceed to production

Reports: Check security-reports/zap-report.html for details

7 Promote to Production

After DAST scan passes (0 FAIL results):

cd deploy/03_prod
docker compose up -d --build

8 Run Integration Tests (Prod)

Verify production deployment:

npx vitest run --config vitest.integration.config.ts tests/integration/prod.test.ts

⚠️ Promotion Checklist

✅ All integration tests pass in staging
✅ All acceptance tests pass in staging
✅ DAST security scan shows 0 FAIL results
✅ DAST WARN results reviewed and documented
✅ Review any error logs: docker compose logs api
✅ Verify product images load correctly
✅ Test checkout flow manually if making payment changes
✅ Schedule production deployments during low-traffic periods

🧪 Running Tests

Test Types

Test Type	Location	Purpose	Required for Prod?
Unit Tests	`src/saleor-product-manager/tests/`	Individual component functionality	Recommended
Integration Tests	`tests/integration/`	API endpoints, service connectivity	✅ Required
Acceptance Tests	`tests/acceptance/`	User journeys, performance, security	✅ Required
🔒 DAST Security Scan	`security-reports/`	OWASP ZAP vulnerability scanning	⚠️ REQUIRED (0 FAIL)

Quick Commands

Run All Unit Tests

cd src/saleor-product-manager
npm test

Run All Integration Tests (All Environments)

npx vitest run --config vitest.integration.config.ts tests/integration/

Run Tests for Specific Environment

# Dev only
npx vitest run --config vitest.integration.config.ts tests/integration/dev.test.ts

# Stage only
npx vitest run --config vitest.integration.config.ts tests/integration/stage.test.ts

# Prod only
npx vitest run --config vitest.integration.config.ts tests/integration/prod.test.ts

Run Acceptance Tests

npx vitest run --config vitest.integration.config.ts tests/acceptance/stage.test.ts

What the Tests Verify

Integration Tests (per environment)

✅ GraphQL API responds correctly
✅ Shop information is configured
✅ Products can be queried
✅ Products have thumbnail images
✅ Categories are accessible
✅ Storefront homepage loads
✅ Products page loads
✅ HTML content is returned

Acceptance Tests

✅ Customer can view homepage
✅ Customer can browse product listings
✅ Products have pricing information
✅ Checkout can be created
✅ Homepage loads within 3 seconds
✅ API responds within 2 seconds
✅ Site is served over HTTPS
✅ Security headers are present

✅ Test Coverage Summary

Unit Tests: 174 tests, 75.93% code coverage
Integration Tests: 26 tests across 3 environments
Acceptance Tests: 8 tests for user journeys
DAST Security Scan: 53+ OWASP ZAP checks

🔒 Security Gate for Production

The following must pass before deploying to production:

✅ Integration Tests (stage) - All pass
✅ Acceptance Tests (stage) - All pass
⚠️ DAST Security Scan - 0 FAIL results

See security-reports/SCAN_RESULTS.md for scan documentation.

🔧 Deployment Troubleshooting

Issue: Container won't start

# Check logs
docker compose logs api

# Force rebuild
docker compose up -d --build --force-recreate

Issue: Images not loading

Verify environment variables are set:

# Check env vars in container
docker exec saleor-api-dev env | grep -E "ENABLE_SSL|PUBLIC_URL"

# Should show:
# ENABLE_SSL=True
# PUBLIC_URL=https://dev.renewed-renaissance.com

If missing, restart with docker compose up -d --force-recreate api

Issue: Tests failing

Check container is running: docker compose ps
Verify health endpoint: curl https://dev.renewed-renaissance.com/health/
Check nginx routing: docker compose logs nginx

Issue: Database connection errors

# Restart database
docker compose restart db

# Wait for healthy status
docker compose ps

⚠️ Common Pitfalls

Don't skip staging: Always test in stage before prod
Check disk space: Docker images can fill up disk
Watch for port conflicts: Ensure ports 8080, 9080, 10080 are available
Environment variables: Changes require container recreation, not just restart

⚙️ Administrator Dashboard Guide