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:
   ```env
   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:

```bash
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

```bash
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

```bash
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

```bash
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**:
   ```graphql
   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**:
   ```graphql
   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