# 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](PUBLIC_SECTOR_TENANCY_MARKETPLACE_AND_DEPLOYMENT_BASELINE.md), [../11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md](../11-references/COMPLETE_CREDENTIAL_EIDAS_PROGRAM_REPOS.md), [../../config/public-sector-program-manifest.json](../../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](../11-references/DBIS_CORE_API_REFERENCE.md) | [04-configuration/MASTER_SECRETS_INVENTORY.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](../11-references/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](../04-configuration/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](../04-configuration/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