211 lines
7.5 KiB
Markdown
211 lines
7.5 KiB
Markdown
# Sankofa Services - Service Descriptions
|
||
|
||
**Last Updated:** 2026-04-13
|
||
**Status:** Active Documentation
|
||
|
||
---
|
||
|
||
## Consolidated runtime (optional)
|
||
|
||
To reduce LXC count for **non-chain** web and to expose **one** Phoenix-facing API origin (GraphQL + `dbis_core` REST behind path routes), see [SANKOFA_PHOENIX_CONSOLIDATED_FRONTEND_AND_API.md](./SANKOFA_PHOENIX_CONSOLIDATED_FRONTEND_AND_API.md). `config/ip-addresses.conf` adds `IP_SANKOFA_WEB_HUB` and `IP_SANKOFA_PHOENIX_API_HUB` (defaulting to today’s portal and Phoenix API IPs until you set hub LXCs in `.env`). Blockchain-adjacent stacks (explorer, RPC, relayers) stay **out** of this consolidation.
|
||
|
||
For **how** the non-chain fleet should be designed (edge cells, API hub, IdP, data) in hyperscaler-style terms—**excluding** the blockchain plane—see [NON_CHAIN_ECOSYSTEM_HYPERSCALER_STYLE_MODEL.md](./NON_CHAIN_ECOSYSTEM_HYPERSCALER_STYLE_MODEL.md).
|
||
|
||
---
|
||
|
||
## 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** (Apollo direct) and **`8080`** (optional Tier-1 **API hub** nginx: `/graphql` → 4000, `/api` → `dbis_core` on `IP_DBIS_API:3000`)
|
||
- **External Access:** https://phoenix.sankofa.nexus, https://www.phoenix.sankofa.nexus (NPM upstream may stay **4000** until you cut over to **8080**)
|
||
|
||
**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
|