# Sovereign Stack Marketplace Services

This document provides quick reference for the Sovereign Stack services implementation.

## Quick Start

### Setup (One Command)

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

### Manual Steps

```bash
# 1. Run migration to add categories
pnpm db:migrate:up

# 2. Seed all services
pnpm db:seed:sovereign-stack

# 3. Verify everything worked
pnpm verify:sovereign-stack
```

## What Was Created

### Database
- **Migration 025**: Adds 5 new product categories + Phoenix publisher
- **Seed Script**: Registers 9 services with versions and pricing

### Services
- 9 service implementation stubs in `src/services/sovereign-stack/`
- All services follow the master plan architecture

### Documentation
- Complete API documentation for each service
- Setup guide and implementation summary

## Services Overview

| Service | Category | Pricing Model | Free Tier |
|---------|----------|---------------|-----------|
| Ledger Service | LEDGER_SERVICES | Usage-based | 10K entries/month |
| Identity Service | IDENTITY_SERVICES | Subscription | - |
| Wallet Registry | WALLET_SERVICES | Hybrid | - |
| Transaction Orchestrator | ORCHESTRATION_SERVICES | Usage-based | 1K tx/month |
| Messaging Orchestrator | ORCHESTRATION_SERVICES | Usage-based | 1K messages/month |
| Voice Orchestrator | ORCHESTRATION_SERVICES | Usage-based | 100 syntheses/month |
| Event Bus | PLATFORM_SERVICES | Subscription | - |
| Audit Service | PLATFORM_SERVICES | Storage-based | 100K logs/month |
| Observability | PLATFORM_SERVICES | Usage-based | 1M metrics/month |

## GraphQL Queries

### List All Phoenix Services

```graphql
query {
  publisher(name: "phoenix-cloud-services") {
    id
    displayName
    products {
      id
      name
      slug
      category
      status
    }
  }
}
```

### Filter by Category

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

## File Locations

- **Migration**: `src/db/migrations/025_sovereign_stack_marketplace.ts`
- **Seed Script**: `src/db/seeds/sovereign_stack_services.ts`
- **Services**: `src/services/sovereign-stack/*.ts`
- **Documentation**: `docs/marketplace/sovereign-stack/*.md`
- **Setup Script**: `scripts/setup-sovereign-stack.sh`
- **Verification**: `scripts/verify-sovereign-stack.ts`

## Troubleshooting

### Migration Fails
- Check database connection in `.env`
- Ensure PostgreSQL is running
- Verify user has CREATE/ALTER permissions

### Seed Fails
- Ensure migration 025 ran successfully
- Check that Phoenix publisher exists
- Review error logs

### Services Not Appearing
- Run verification: `pnpm verify:sovereign-stack`
- Re-run seed: `pnpm db:seed:sovereign-stack`
- Check GraphQL query filters

## Next Steps

1. ✅ Run setup script
2. ✅ Verify services appear in marketplace
3. ⏳ Implement full service logic (stubs are ready)
4. ⏳ Build provider adapters
5. ⏳ Create API endpoints
6. ⏳ Build frontend marketplace UI

## Support

- **Documentation**: `docs/marketplace/sovereign-stack/`
- **Setup Guide**: `docs/marketplace/sovereign-stack/SETUP.md`
- **Implementation Summary**: `docs/marketplace/sovereign-stack/IMPLEMENTATION_SUMMARY.md`