Deployment
Environments
| Env | Namespace | ArgoCD App |
|---|---|---|
| UAT | pos-uat | pos-partner-api |
| Prod | pos-prod | pos-partner-api-prod |
The ArgoCD app for each environment owns the workload resources: Deployment,
Service, CronJob, NetworkPolicy, ServiceMonitor, migration Job, and
InfisicalSecret resources. Public HTTPRoute resources for
pos-partner-api.uat.digiwedge.com and pos-partner-api.digiwedge.com are
owned by the centralized kub-jhb-02-gateway app so ArgoCD has one writer for
the edge route.
Reconciliation sync runtime
Reconciliation freshness is maintained by a Kubernetes-owned CronJob, not an in-process API cron.
- CronJob:
pos-partner-api-reconciliation-sync - Execution path: app image runs
dist/apps/pos/partner-api/main.js reconciliation-sync-once - Required secret:
POS_DATA_DATABASE_URL - Optional secret:
POS_RECONCILIATION_SYNC_STALE_MINUTES
GET /admin/pos/reconciliation/report is read-only, including on an empty install. It no longer bootstraps sync state by writing through the report path.
Replica policy
pos-partner-api is intentionally deployed as a single replica today.
Reason:
- the API workload has not yet been validated for multi-replica rollout under the current POS runtime and migration contract
- reconciliation sync is already isolated in the
pos-partner-api-reconciliation-syncCronJob, so API replica count does not create additional scheduled reconciliation writers
Do not scale this deployment above 1 replica until the API runtime has explicit multi-replica readiness proof for partner request handling, migrations, observability, and rollback.
Secrets
All secrets managed by Infisical at path /pos/partner-api.
| Key | Source |
|---|---|
POS_DATA_DATABASE_URL | Reference to /dependencies/pos canonical |
MCA_API_URL | Xano ZA API endpoint |
MCA_API_KEY | Xano ZA API key |
MCA_API_DATA_SOURCE | Xano workspace slug (extracted from API URL suffix, e.g. zr6jZOEU) |
MCA_SA_LIVE_V1_URL | Legacy ZA member database for member/card lookup; intended canonical source is /dependencies/mca-v1-za-db |
MCA_UK_LIVE_V1_URL | Legacy UK member database for member/card lookup; intended canonical source is /dependencies/mca-v1-uk-db |
POS_PARTNER_API_KEY | Current partner authentication key |
POS_PARTNER_API_KEY_ID | Optional non-secret generation label for POS_PARTNER_API_KEY |
POS_PARTNER_API_NEXT_KEY | Optional staged partner authentication key for rotation |
POS_PARTNER_API_NEXT_KEY_ID | Optional non-secret generation label for POS_PARTNER_API_NEXT_KEY |
POS_PARTNER_ID | Optional non-secret partner label attached to auth context |
POS_PARTNER_AUTH_RATE_LIMIT_MAX | Optional fixed-window auth limiter maximum; defaults to 120 |
POS_PARTNER_AUTH_RATE_LIMIT_WINDOW_MS | Optional fixed-window auth limiter window; defaults to 60000 |
POS_PARTNER_MEMBER_ID_SECRET | HMAC secret for member ID validation |
POS_PARTNER_ADMIN_KEY | Required admin authentication key for /api/admin/pos/* operator routes |
POS_PARTNER_MEMBER_SOURCE_DEFAULT | Default member source (mca_v1_za, mca_v1_uk, scl) |
POS_PARTNER_MEMBER_SOURCE_BY_CLUB | Optional per-club overrides, format club:source,club:source |
CRM_DATABASE_URL and MCA_V2_POSTGRES_URL are not part of the pos-partner-api runtime
contract.
mca_v1_za and mca_v1_uk are legacy schemas, but they are active POS
read-side dependencies. Keep using the Prisma packages for routed member/card
lookup until the SCL bridge is implemented. Do not replace them with older
libs/mca/**, @digiwedge/mca-*, or MCA GraphQL application libraries; those
surfaces are legacy MCA application code and are not part of the POS partner API
runtime contract.
The repo inventory now treats both MCA v1 URLs as shared dependency credentials. Before rollout, /pos/partner-api
must resolve valid values or references for both keys in the target environment.
The API constructs MCA v1 SQL clients lazily on the first routed member lookup
for each region; startup should connect only to POS_DATA_DATABASE_URL.
Publish
Image published via pos-partner-api-publish.yml on push to main (paths-filtered) or pos-partner-api-v* tag.
Prisma Migration
Sync-wave bootstrap order on each sync:
- Tracked InfisicalSecret resources at wave
-2 - Harbor seeder RBAC (ServiceAccount/Role/RoleBinding) at wave
-1 - Harbor credentials seed at Sync wave
0 - Prisma migration job at Sync wave
1
Migrate job command:
npx prisma migrate deploy --schema=/app/prisma/pos-data/schema.prisma