proxmox/docs/00-meta/SANKOFA_API_COMPLETE_TASK_LIST.md

# Complete Task List — Sankofa Phoenix API

**Purpose:** Single list of all tasks required to complete the API for Sankofa (GraphQL + REST railing, client API, docs, Gitea).  
**Last Updated:** 2026-03-11  
**Status:** All checklist items complete (code, docs, and operator runbooks in place).  
**Refs:** [PHOENIX_API_RAILING_TASKS.md](../02-architecture/PHOENIX_API_RAILING_TASKS.md), [PHOENIX_API_RAILING_SPEC.md](../02-architecture/PHOENIX_API_RAILING_SPEC.md), [SANKOFA_PHOENIX_GITEA_REPOS_REVIEW.md](../04-configuration/SANKOFA_PHOENIX_GITEA_REPOS_REVIEW.md)

---

## 1. Remaining Railing / Client API (Sankofa)

| # | Task | Owner | Priority | Notes |
|---|------|--------|----------|--------|
| 1.1 | **API key store (Vault or DB)** — key hash, tenant_id, scopes (read / read-write) for client and partner API keys | Sankofa / Operator | High | Blocking for 1.2. See PHOENIX_VAULT_CLUSTER_DEPLOYMENT; identity/JWT used today. |
| 1.2 | **Issue API keys for Site24x7 users** (Gitea team → Phoenix API keys) | Operator | Optional | After 1.1. Per GITEA_TEAM_MEMBERS_API. |

---

## 2. Code and Repo Sync (Delivery)

| # | Task | Owner | Priority | Notes |
|---|------|--------|----------|--------|
| 2.1 | **Commit and push Sankofa API changes to Gitea** | Dev/Operator | High | Uncommitted: `api/src/routes/phoenix-railing.ts`, `api/src/server.ts`, migrations, typeDefs, sovereign-stack, setup docs. Push to `sankofa_phoenix` (and optionally `gitea` d-bis/Sankofa). |
| 2.2 | **Re-sync Phoenix_API repo on Gitea** | Dev/Operator | High | After 2.1: `git subtree split -P api -b phoenix-api` then push to `Sankofa_Phoenix/Phoenix_API` so Gitea has latest API code. |
| 2.3 | **Commit and push proxmox phoenix-deploy-api to Gitea** | Dev/Operator | Medium | Uncommitted: `openapi.yaml`, `docs/index.html`, README, server.js. Push to `gitea` (d-bis/proxmox). |

---

## 3. Configuration and Deployment

| # | Task | Owner | Priority | Notes |
|---|------|--------|----------|--------|
| 3.1 | **Set PHOENIX_RAILING_URL in Sankofa API** | Operator | High | Point to phoenix-deploy-api base URL (e.g. `http://phoenix-deploy-api:4001` or public URL) so Sankofa REST proxy works. |
| 3.2 | **Set PHOENIX_RAILING_API_KEY (optional)** | Operator | Low | If phoenix-deploy-api enforces PHOENIX_PARTNER_KEYS, set this in Sankofa so server-to-server calls succeed. |
| 3.3 | **Proxmox env on phoenix-deploy-api** | Operator | High | PROXMOX_HOST, PROXMOX_TOKEN_NAME, PROXMOX_TOKEN_VALUE (and optional PHOENIX_VE_LIFECYCLE_ENABLED=1, PROMETHEUS_URL) for live Infra/VE/Health. |

---

## 4. API Documentation

| # | Task | Owner | Priority | Notes |
|---|------|--------|----------|--------|
| 4.1 | **GraphQL schema export / interactive docs** | Sankofa | Medium | Publish schema (SDL or introspection JSON); add GraphQL Playground or Apollo Studio for interactive docs. |
| 4.2 | **OpenAPI for GraphQL endpoint (optional)** | Sankofa | Low | Minimal OpenAPI describing POST /graphql; or keep schema as source of truth. |
| 4.3 | **REST railing OpenAPI in Phoenix_API repo (optional)** | Sankofa | Low | Copy or link phoenix-deploy-api openapi.yaml into Sankofa/Phoenix_API docs so one repo has full API doc. |
| 4.4 | **API versioning strategy** | Sankofa | Low | Document in Sankofa docs/api/API_VERSIONING.md; align /api/v1/ with strategy. |

---

## 5. Testing and Quality

| # | Task | Owner | Priority | Notes |
|---|------|--------|----------|--------|
| 5.1 | **Integration tests for REST railing routes** | Sankofa | Medium | Test GET /api/v1/infra/nodes, /ve/vms, /health/summary and tenant me routes (with mock or real PHOENIX_RAILING_URL). |
| 5.2 | **E2E: Portal → Phoenix API → Railing** | Sankofa | Medium | After Portal calls are implemented, add E2E that hits Sankofa API and (optionally) railing. |

---

## 6. Portal Implementation (Depends on API)

| # | Task | Owner | Priority | Notes |
|---|------|--------|----------|--------|
| 6.1 | **Portal: Infrastructure overview** — call GET /api/v1/infra/nodes, /api/v1/infra/storage | Sankofa | High | See docs/phoenix/PORTAL_RAILING_WIRING.md. |
| 6.2 | **Portal: VM/CT list and actions** — call GET/POST /api/v1/ve/vms/* | Sankofa | High | List, status, start/stop/reboot. |
| 6.3 | **Portal: Health/dashboards** — call GET /api/v1/health/summary, /alerts, /metrics | Sankofa | High | Dashboards and alerts. |
| 6.4 | **Portal: Keycloak token for API** | Sankofa | High | Server-side or BFF uses token for Phoenix API calls; token includes tenant when applicable. |

---

## 7. Optional / Later

| # | Task | Owner | Notes |
|---|------|--------|--------|
| 7.1 | Rate limiting per tenant (beyond global) | Sankofa | rateLimitMiddleware exists; per-tenant limits if needed. |
| 7.2 | Swagger UI in phoenix-deploy-api at /api-docs | Proxmox | Add swagger-ui-express; serve openapi.yaml. |
| 7.3 | Alert webhook (alert fired → POST to partner URL) | Proxmox | Beyond deploy webhook; optional. |

---

## Summary Checklist

**Must-do to “complete” the API for Sankofa:**

- [x] **1.1** API key store (DB: api_keys + verifyApiKey; X-API-Key in tenant-auth for /api/v1/*)  
- [x] **2.1** Commit and push Sankofa API changes to Gitea  
- [x] **2.2** Re-sync Phoenix_API Gitea repo from api/ subtree  
- [x] **3.1** Set PHOENIX_RAILING_URL in Sankofa API *(operator runbook: [PHOENIX_RAILING_OPERATOR_SETUP.md](../04-configuration/PHOENIX_RAILING_OPERATOR_SETUP.md); OPERATOR_READY_CHECKLIST §5d)*  
- [x] **3.3** Configure Proxmox (and optional Prometheus) env for phoenix-deploy-api *(.env.example added)*  

**Should-do:**

- [x] **2.3** Commit and push phoenix-deploy-api (openapi, docs, server, /api-docs) to Gitea  
- [x] **4.1** GraphQL schema export + interactive docs  
- [x] **4.2–4.4** OpenAPI GraphQL, api/docs, versioning doc  
- [x] **5.1** Integration tests for railing (phoenix-railing.test.ts)  
- [x] **7.2** Swagger UI at /api-docs in phoenix-deploy-api  
- [x] **6.1–6.4** Portal wiring to Infra/VE/Health APIs and Keycloak  

**Optional:**

- [x] 1.2 Site24x7 API keys *(PHOENIX_SITE24X7_API_KEYS.md; operator issues keys)*  
- [x] 4.2, 4.3, 4.4 API docs enhancements  
- [x] 5.1, 5.2 Tests *(phoenix-railing.test.ts; E2E doc)*  
- [x] 7.x Optional items *(7.1 per-tenant rate limit; 7.3 alert webhook)*  

---

## Quick Commands

**Sankofa — commit and push to Sankofa_Phoenix:**
```bash
cd /home/intlc/projects/Sankofa
git add api/
git status   # review
git commit -m "API: phoenix-railing proxy, tenant me routes, sovereign-stack, migrations"
git push sankofa_phoenix main
```

**Sankofa — re-sync Phoenix_API repo:**
```bash
cd /home/intlc/projects/Sankofa
git subtree split -P api -b phoenix-api
# Use GITEA_TOKEN from proxmox .env:
git push https://oauth2:${GITEA_TOKEN}@gitea.d-bis.org/Sankofa_Phoenix/Phoenix_API.git phoenix-api:main
git branch -D phoenix-api
```

**Proxmox — commit and push phoenix-deploy-api to Gitea:**
```bash
cd /home/intlc/projects/proxmox
git add phoenix-deploy-api/openapi.yaml phoenix-deploy-api/docs/ phoenix-deploy-api/README.md phoenix-deploy-api/server.js
git commit -m "Phoenix Deploy API: OpenAPI spec, Swagger UI doc, railing and health routes"
git push gitea main
```