Sankofa/api/README_SOVEREIGN_STACK.md

Sovereign Stack Marketplace Services

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

Quick Start

Setup (One Command)

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

Manual Steps

# 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

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

Filter by Category

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