proxmox/docs/02-architecture/SERVICE_DESCRIPTIONS.md

Sankofa Services - Service Descriptions

Last Updated: 2026-03-25 Status: Active Documentation

---

Brand and Product Relationship

Company and Product Analogy

Sankofa = Company/Brand (like Microsoft, Google, Amazon)
Phoenix = Cloud Platform/Product (like Azure, GCP, AWS)
Sankofa Phoenix = Complete Product Name (like Microsoft Azure, Google Cloud Platform, Amazon Web Services)

Service Overview

This document describes the purpose and function of each service in the Sankofa Phoenix deployment.

---

Services

1. Sankofa Portal (sankofa.nexus)

• Description: Company/Brand Website (like Microsoft.com, Google.com, Amazon.com)
• Purpose: Main corporate website for Sankofa
• VMID: 7801
• IP: 192.168.11.51
• Port: 3000
• External Access: https://sankofa.nexus, https://www.sankofa.nexus

Details:

• Next.js-based corporate website
• Main public-facing brand website
• Similar to Microsoft.com, Google.com, or Amazon.com

---

2. Phoenix API (phoenix.sankofa.nexus)

• Description: Cloud Platform Portal (like Azure Portal, GCP Console, AWS Console)
• Purpose: Cloud infrastructure management portal (API service)
• VMID: 7800
• IP: 192.168.11.50
• Port: 4000
• External Access: https://phoenix.sankofa.nexus, https://www.phoenix.sankofa.nexus

Details:

• GraphQL API service for Phoenix cloud platform
• Provides cloud infrastructure management capabilities
• Similar to Microsoft Azure Portal, Google Cloud Console, or AWS Management Console
• API endpoints:
  • GraphQL: /graphql
  • GraphQL WebSocket: /graphql-ws
  • Health: /health

Cross-reference: Public-sector tenancy, service catalog vs marketing boundaries, and SMOA / Complete Credential repo pointers: PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md, ../11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md, ../../config/public-sector-program-manifest.json.

---

3. SolaceScanScout (Explorer)

• Description: Blockchain Explorer for ChainID 138
• Purpose: Block explorer service based on Blockscout
• Status: Separate service (not part of this deployment)
• Chain ID: 138
• Technology: Blockscout-based

Details:

• Block explorer for blockchain transactions on ChainID 138
• Provides transaction and block information
• Based on Blockscout explorer technology
• Similar to Etherscan or other blockchain explorers
• Not included in the current Sankofa Phoenix deployment cutover

---

4. Keycloak (Identity Management)

• Description: Identity and Access Management
• Purpose: Authentication and authorization service
• VMID: 7802
• IP: 192.168.11.52
• Port: 8080
• Internal Access: http://192.168.11.52:8080

Details:

• Single Sign-On (SSO) service
• User authentication and authorization
• Admin interface: /admin
• Health endpoint: /health/ready

---

5. PostgreSQL (Database)

• Description: Database Service
• Purpose: Data storage for all services
• VMID: 7803
• IP: 192.168.11.53
• Port: 5432
• Internal Access: 192.168.11.53:5432

Details:

• PostgreSQL 16 database
• Stores data for Keycloak, Phoenix API, and Sankofa Portal
• Internal access only (not exposed externally)

---

Service Relationships

Internet
   ↓
NPMplus (Reverse Proxy + SSL)
   ↓
   ├─→ sankofa.nexus → Sankofa Portal (Company Website - like Microsoft.com)
   ├─→ phoenix.sankofa.nexus → Phoenix API (Cloud Platform - like Azure Portal)
   └─→ SolaceScanScout (Block Explorer - Separate service)
   
Backend Services:
   ├─→ Keycloak (Authentication)
   └─→ PostgreSQL (Database)

Brand/Product Analogy:

• Sankofa = Microsoft (company/brand)
• Phoenix = Azure (cloud platform)
• Sankofa Phoenix = Microsoft Azure (complete product)
• Sankofa Portal = Microsoft.com (corporate website)
• Phoenix Portal = Azure Portal (cloud management console)

---

Service Dependencies

• Sankofa Portal depends on:

  • Phoenix API (for backend functionality)
  • Keycloak (for authentication)

• Phoenix API depends on:

  • PostgreSQL (for data storage)
  • Keycloak (for authentication)

• Keycloak depends on:

  • PostgreSQL (for user data storage)

---

6. Crypto.com OTC Integration (DBIS Core)

• Description: Institutional OTC trading via Crypto.com Exchange OTC 2.0 API
• Purpose: Request-for-Quote (RFQ), deal execution, settle-later tracking, FX price provider
• Location: dbis_core/src/core/exchange/crypto-com-otc/
• API Path: /api/v1/crypto-com-otc (on dbis-api.d-bis.org)
• Status: Optional - requires CRYPTO_COM_API_KEY and CRYPTO_COM_API_SECRET

Details:

• REST and WebSocket clients for Crypto.com OTC 2.0 API
• FX service integration for market price (when OTC quotes cached)
• Deal persistence to otc_trades table
• Settle-later limit and unsettled amount monitoring
• Rate limiting (1 req/s REST, 2 req/s WebSocket)
• Retry with exponential backoff

Related: 11-references/DBIS_CORE_API_REFERENCE.md | 04-configuration/MASTER_SECRETS_INVENTORY.md

---

7. Exchange Registry (DBIS Core)

• Description: Multi-exchange price aggregation (Binance, Kraken, Oanda, FXCM)
• Location: dbis_core/src/core/exchange/
• API Path: /api/v1/exchange (price, providers)
• Related: DBIS_CORE_API_REFERENCE.md

---

8. Ramp API (metamask-integration)

• Description: Fiat on/off-ramp session creation (MoonPay, Ramp, Onramper, Transak, Banxa, Coinbase, Stripe, Cybrid, Sardine, HoneyCoin)
• Location: metamask-integration/src/ramps/
• API: POST /ramps/on-ramp/session, POST /ramps/off-ramp/session, GET /ramps/quote, GET /ramps/providers
• Related: MASTER_SECRETS_INVENTORY.md

---

9. DeFi Router (alltra-lifi-settlement)

• Description: DEX aggregator - 1inch, ParaSwap, 0x (best-route selection)
• Location: alltra-lifi-settlement/src/payments/
• Related: MASTER_SECRETS_INVENTORY.md

---

Network Architecture

All services are deployed on:

• Network: VLAN 11 (192.168.11.0/24)
• Gateway: 192.168.11.11 (Proxmox host)
• Host: r630-01 (Proxmox host at 192.168.11.11)

---

Last Updated: 2026-01-31