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, PHOENIX_API_RAILING_SPEC.md, 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:

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

Should-do:

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

Optional:

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

---

Quick Commands

Sankofa — commit and push to Sankofa_Phoenix:

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:

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:

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