Sankofa/docs/marketplace/sovereign-stack/SETUP.md

Sovereign Stack Marketplace Setup Guide

This guide walks you through setting up the Sovereign Stack services in the Sankofa marketplace.

Prerequisites

1. Database: PostgreSQL database must be running and accessible
2. Environment Variables: .env file with database credentials:

   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=sankofa
   DB_USER=postgres
   DB_PASSWORD=your_password
   

3. Node.js: Node.js 18+ and pnpm installed

Quick Setup

Run the automated setup script:

cd /home/intlc/projects/Sankofa/api
./scripts/setup-sovereign-stack.sh

This script will:

1. Run database migrations (including migration 025 for new categories)
2. Seed all 9 Sovereign Stack services
3. Verify the setup

Manual Setup

If you prefer to run steps manually:

Step 1: Run Migrations

cd /home/intlc/projects/Sankofa/api
pnpm db:migrate:up

This will:

• Add new product categories (LEDGER_SERVICES, IDENTITY_SERVICES, etc.)
• Create/update Phoenix Cloud Services publisher

Step 2: Seed Services

pnpm db:seed:sovereign-stack

This will:

• Create Phoenix publisher (if not exists)
• Register all 9 Sovereign Stack services
• Create product versions (v1.0.0)
• Set up pricing models

Step 3: Verify Setup

pnpm verify:sovereign-stack

This will verify:

• Phoenix publisher exists and is verified
• All 9 services are registered
• Product versions exist
• Pricing models are configured

Expected Output

After successful setup, you should see:

✅ Phoenix publisher found: Phoenix Cloud Services
✅ Found 9 Phoenix services:
  - Phoenix Audit Service
  - Phoenix Event Bus
  - Phoenix Identity Service
  - Phoenix Ledger Service
  - Phoenix Messaging Orchestrator
  - Phoenix Observability Stack
  - Phoenix Transaction Orchestrator
  - Phoenix Voice Orchestrator
  - Phoenix Wallet Registry
✅ Services span 5 categories
✅ Found 9 product versions
✅ Found 9 pricing models

Troubleshooting

Migration Fails

• Check database connection in .env
• Ensure PostgreSQL is running
• Verify database user has CREATE/ALTER permissions

Seeding Fails

• Ensure migration 025 has run successfully
• Check that Phoenix publisher was created
• Review error messages for specific issues

Verification Shows Missing Services

• Re-run: pnpm db:seed:sovereign-stack
• Check database logs for errors
• Verify product slugs match expected values

Accessing the Marketplace

Once setup is complete:

1. Via GraphQL API:

   query {
     products(filter: { publisherId: "<phoenix-publisher-id>" }) {
       id
       name
       slug
       category
       status
     }
   }
   

2. Via Portal: Navigate to https://portal.sankofa.nexus/marketplace

3. Filter by Category:

   query {
     products(filter: { category: LEDGER_SERVICES }) {
       name
       description
       pricing {
         pricingType
         basePrice
       }
     }
   }
   

Next Steps

1. Review Service Documentation: See individual service docs in this directory
2. Test API Endpoints: Use the service stubs to test functionality
3. Subscribe to Services: Use the marketplace to subscribe to services
4. Monitor Usage: Track usage via the billing dashboard

Support

If you encounter issues:

• Check logs: pnpm verify:sovereign-stack
• Review migration status: pnpm db:migrate:status
• Contact support: support@sankofa.nexus