proxmox/docs/02-architecture/EXPECTED_WEB_CONTENT.md

# Web Properties — Ground Truth & Validation

**Last Updated:** 2026-03-27  
**Document Version:** 1.2  
**Status:** Active Documentation

---

_Last reviewed: authoritative alignment checkpoint_

This document reconciles **expected intent**, **current deployment state**, and **functional role** for each public-facing or semi-public web property.

**Quick matrix (every FQDN: web vs API vs RPC, and what clients should see):** [FQDN_EXPECTED_CONTENT.md](../04-configuration/FQDN_EXPECTED_CONTENT.md).

---

## Sankofa.nexus and Phoenix — hostname model (canonical)

| Hostname | Tier | Access | Expected content |
|----------|------|--------|------------------|
| `sankofa.nexus` | **Public web** | Unauthenticated visitors | **Sankofa — Sovereign Technologies:** corporate / brand public site (marketing, narrative, entry points). |
| `phoenix.sankofa.nexus` | **Public web** | Unauthenticated visitors (for public pages) | **Phoenix Cloud Services** (a division of Sankofa): public-facing web for the cloud services division. |
| `keycloak.sankofa.nexus` | **SSO infrastructure** (IdP) | Browser hits login + token flows; operators use admin | **Keycloak:** OIDC/SAML identity provider behind client SSO. Serves realm login UI, well-known and token endpoints, and **admin console** at `/admin`. **Consumes:** `admin.sankofa.nexus` and `portal.sankofa.nexus` (and other registered clients) redirect here for authentication; it does **not** replace those hostnames. |
| `admin.sankofa.nexus` | **Client SSO** | SSO (system-mediated) | **Client administration of access:** who can access what (invites, roles, org settings, access policy). |
| `portal.sankofa.nexus` | **Client SSO** | SSO | **Client workspace:** Phoenix cloud services, Sankofa Marketplace subscriptions, and other **client-facing** services behind one SSO boundary. |
| `dash.sankofa.nexus` | **Operator / systems** | **IP allowlisting** + **system authentication** + **MFA** | **Internal systems dashboard:** administration across Sankofa, Phoenix, Gitea, and additional platform systems—not the same trust boundary as client `admin` / `portal`. |

**Placement of Keycloak:** Treat `keycloak.sankofa.nexus` as the **shared IdP** for the **SSO-gated client tier** (`admin`, `portal`). Users often see Keycloak only during login redirects. **`dash.sankofa.nexus`** is a separate, stricter surface (network + MFA); it may integrate with Keycloak or other system identity depending on implementation, but the **documented intent** is IP-gated operator admin, not “client self-service SSO” like `portal`.

---

## 1. sankofa.nexus (public — Sovereign Technologies)

**Role:** Public corporate web for **Sankofa — Sovereign Technologies.**  
**Comparable to:** Company apex domain (e.g. microsoft.com).

### Expected content
- Brand, mission, Sovereign Technologies positioning  
- Philosophy narrative (**Remember → Retrieve → Restore → Rise**)  
- Paths into Phoenix and commercial / program entry points (links may target `phoenix.sankofa.nexus`, `portal.sankofa.nexus`, etc.)

### Current deployment (typical)
- **VMID:** 7801 · **Port:** 3000 (Next.js) — see [ALL_VMIDS_ENDPOINTS.md](../04-configuration/ALL_VMIDS_ENDPOINTS.md)

### Notes
- **Unauthenticated public web** is the **intent** for this hostname; authenticated client work belongs on **`portal.sankofa.nexus`**.

---

## 2. phoenix.sankofa.nexus (public — Phoenix Cloud Services)

**Role:** Public-facing web for **Phoenix Cloud Services**, a division of Sankofa.  
**Comparable to:** Public cloud division landing (e.g. azure.microsoft.com style), not the raw JSON-RPC layer.

### Expected content
- Division branding, service overview, how Phoenix fits under Sankofa  
- Clear separation from corporate apex (`sankofa.nexus`)

### Technical note (same origin today)
- **VMID 7800** historically exposes **API-first** surfaces (`/health`, `/graphql`, `/graphql-ws`). Public **marketing or division web** may be served from the same stack or split later; this document states **product intent** for the hostname. Prefer not to present the apex `sankofa.nexus` portal app as if it were “Phoenix public web.”

---

## 3. keycloak.sankofa.nexus (SSO — identity provider)

**Role:** **OIDC/SAML IdP** for the Sankofa / Phoenix client ecosystem.  
**VMID:** 7802 (typical)

### Expected content / behavior
- End-user **login** (realm themes), **logout**, **token** and **well-known** endpoints  
- **Admin console** at `/admin` for realm and client configuration (operator-controlled)

### Relationship
- **`admin.sankofa.nexus`** and **`portal.sankofa.nexus`** are the **client-facing apps**; Keycloak is where **authentication** completes for those SSO flows.

---

## 4. admin.sankofa.nexus (client SSO — access administration)

**Role:** **SSO-authenticated** surface for **clients** to **administer access** (users, groups, delegations, tenant access policy as productized).

### Expected content
- IAM-style administration for client orgs (not raw Keycloak admin—that remains on Keycloak’s `/admin` for platform operators).

---

## 5. portal.sankofa.nexus (client SSO — services and marketplace)

**Role:** **SSO-authenticated** **client portal** for day-to-day use of subscribed services.

### Expected content
- **Phoenix cloud** service entry and consoles (as entitled)  
- **Sankofa Marketplace** subscriptions and management  
- Other **client-facing** services behind the same SSO boundary

**Public URL policy (env):** NextAuth / OIDC public URL may be set to `https://portal.sankofa.nexus` (see `scripts/deployment/sync-sankofa-portal-7801.sh`).

---

## 6. dash.sankofa.nexus (IP-gated — system admin + MFA)

**Role:** **Operator and systems administration** across Sankofa, Phoenix, Gitea, and related infrastructure.

### Access model
- **IP address gating** (allowlisted networks / VPN / office)  
- **System authentication** + **MFA** (stricter than public internet client SSO)

### Expected content
- Unified or linked **admin** views for platform systems—not a substitute for `portal.sankofa.nexus` client self-service.

---

## 7. explorer.d-bis.org
**Service Name:** SolaceScanScout  
**Role:** Block Explorer for ChainID 138  
**Technology:** Blockscout-based  
**Comparable To:** Etherscan, PolygonScan, BscScan

### Intended Function
- Public transparency layer for ChainID 138
- Settlement and transaction inspection

### Expected Capabilities
- Latest blocks viewer
- Transaction browser
- Address explorer (balances, history)
- Token explorer (ERC-20 or equivalents)
- Network metrics and statistics
- Search (block / tx / address)
- ChainID 138 network identification

### Current Deployment
- **Status:** ✅ Active, separate service
- **VMID:** 5000
- **Address:** 192.168.11.140
- **Isolation:** Independent from Phoenix & Sankofa Portal

### Notes
- Correctly positioned as **public infrastructure**
- No coupling to portal auth systems

---

## 8. blockscout.defi-oracle.io
**Service Name:** Blockscout Explorer (Generic)  
**Role:** Independent / Reference Blockscout Instance

### Intended Function
- General-purpose blockchain explorer
- Testing, comparison, or alternate network usage

### Capabilities
- Standard Blockscout UI
- Smart contract verification
- API access for blockchain data

### Current Status
- Separate and unrelated to ChainID 138 branding
- **Not** the canonical DBIS explorer

---

## Canonical Alignment Summary

| Domain | Purpose | Public web | Auth model | Canonical |
|--------|---------|------------|------------|-------------|
| sankofa.nexus | Sovereign Technologies (corporate) | Yes (intended) | None for public pages | ✅ |
| phoenix.sankofa.nexus | Phoenix Cloud Services (division) | Yes (intended) | None for public pages | ✅ |
| keycloak.sankofa.nexus | IdP for client SSO | Login UI only | IdP + admin | ✅ |
| admin.sankofa.nexus | Client access administration | No | SSO | ✅ |
| portal.sankofa.nexus | Client services + marketplace | No | SSO | ✅ |
| dash.sankofa.nexus | Systems / operator admin | No | IP + system auth + MFA | ✅ |
| explorer.d-bis.org | ChainID 138 Explorer | Yes | No | ✅ |
| blockscout.defi-oracle.io | Generic Explorer | Yes | No | ❌ |

---

## Confirmed Architectural Intent
- **sankofa.nexus** = public brand for **Sankofa — Sovereign Technologies**  
- **phoenix.sankofa.nexus** = public web for **Phoenix Cloud Services** (division of Sankofa); API surfaces may share deployment  
- **portal / admin** = **client SSO** tier; **Keycloak** = shared IdP  
- **dash** = **IP-gated** operator systems admin with **MFA**  
- **DBIS Explorer** = public transparency + settlement inspection  
- **No accidental overlap** between public marketing, client SSO, operator dash, and explorer transparency

---

## Open Decisions (Explicitly Unresolved)

**Critical:** These decisions remain **explicitly unresolved**. Do not collapse them prematurely.

### 1. Phoenix UI vs API on `phoenix.sankofa.nexus`
**Status:** Implementation may still be API-first on VMID 7800 while **hostname intent** is public division web; reconcile with a dedicated static/marketing upstream or path split if needed.

---

### 2. Rich console UI for Phoenix (beyond public division web)
**Status:** Open decision point

**Question:** Whether authenticated **Phoenix product consoles** live primarily on **`portal.sankofa.nexus`** (SSO) vs additional surfaces.

**Flexibility:** Public division web on `phoenix.sankofa.nexus` does not preclude deep consoles behind **`portal`** SSO.

---

### 3. Branding Linkage
**Status:** Open decision point

**Question:** Branding linkage between DBIS Core products and explorer UI

**Options:**
- Maintain independent branding
- Align with DBIS Core products
- Federate with other explorers

**Note:** Explorer independence is intentional, not permanent.

---

### 4. Future Evolution Pathways (Non-Binding)

These are **possible futures**, not commitments:

- NPM `www.*` → apex **301** policy vs additional marketing hostnames
- `admin` / `portal` / `dash` upstream targets on NPM (when split from legacy single-host deployments)
- Delegated Phoenix UI development
- Explorer rebrand or federation
- Additional service surfaces

**Why Documented:**
- Signals foresight without commitment
- Prevents future teams from assuming "this was never considered"
- Preserves optionality for governance decisions

---

## Service Relationship Diagram

```
Internet
   ↓
NPMplus (Reverse Proxy + SSL)
   ↓
   ├─→ sankofa.nexus              → Public web: Sankofa — Sovereign Technologies
   ├─→ phoenix.sankofa.nexus      → Public web: Phoenix Cloud Services (division)
   │
   ├─→ admin.sankofa.nexus        → Client SSO: administer access
   ├─→ portal.sankofa.nexus       → Client SSO: Phoenix cloud + marketplace + client services
   │        └─ (redirects) ──→ keycloak.sankofa.nexus  (OIDC/SAML IdP, VMID 7802)
   │
   ├─→ dash.sankofa.nexus         → IP allowlist + system auth + MFA: operator systems admin
   │        (Sankofa, Phoenix, Gitea, …)
   │
   ├─→ explorer.d-bis.org         → SolaceScanScout (ChainID 138, no login for browse)
   └─→ blockscout.defi-oracle.io  → Generic Blockscout (not canonical 138 explorer)

Backend (typical):
   ├─→ Keycloak VMID 7802, PostgreSQL VMID 7803
   └─→ Phoenix API VMID 7800, Sankofa web VMID 7801 (until admin/portal/dash are split to own upstreams)
```

---

## Deployment Status

### Active Services

| Service | Domain | VMID | IP | Port | Status | Access model |
|---------|--------|------|-----|------|--------|----------------|
| **Phoenix** (API today; division hostname) | phoenix.sankofa.nexus | 7800 | 192.168.11.50 | 4000 | ✅ Active | Public web **intent**; API paths coexist |
| **Sankofa public web** | sankofa.nexus | 7801 | 192.168.11.51 | 3000 | ✅ Active | Public **intent** (see hostname model) |
| **Keycloak IdP** | keycloak.sankofa.nexus | 7802 | (see ALL_VMIDS) | 8080 | ✅ Active | IdP + `/admin` |
| **Client admin (SSO)** | admin.sankofa.nexus | ⚠️ TBD | ⚠️ TBD | ⚠️ TBD | Target hostname | SSO |
| **Client portal (SSO)** | portal.sankofa.nexus | ⚠️ TBD | ⚠️ TBD | ⚠️ TBD | Target hostname | SSO |
| **Operator dash** | dash.sankofa.nexus | ⚠️ TBD | ⚠️ TBD | ⚠️ TBD | Target hostname | IP + MFA |
| **SolaceScanScout** | explorer.d-bis.org | 5000 | 192.168.11.140 | 80/4000 | ✅ Active | Public |
| **Blockscout** | blockscout.defi-oracle.io | ⚠️ TBD | ⚠️ TBD | ⚠️ TBD | ⚠️ Separate | Public |

---

## Brand/Product Relationship Context

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

- **sankofa.nexus** = Public company site — **Sankofa — Sovereign Technologies**
- **phoenix.sankofa.nexus** = Public division site — **Phoenix Cloud Services**
- **portal.sankofa.nexus** / **admin.sankofa.nexus** = **Client SSO** apps (Keycloak as IdP)
- **dash.sankofa.nexus** = **IP-gated** operator systems admin (**MFA**)
- **explorer.d-bis.org** = Blockchain explorer (like Etherscan)
- **blockscout.defi-oracle.io** = Generic explorer instance

---

**Review Status:** Authoritative alignment checkpoint