VR_CMS_API — knowledge digest

VR_CMS_API — knowledge digest

The CMS backend: collections, collection objects, integrations, media uploads, audit logging, content versioning. Maps to NEXT_PUBLIC_CMS_URL. Express + serverless-express on Lambda (Node 20, arm64), JavaScript, MongoDB/Mongoose, Cognito JWT via API Gateway, SAM. Read C:\repos\VR_CMS_API\CLAUDE.md for full route lists and depth.

Architecture — 5 Lambdas

getCollectionInfo (read-only + dashboard + audit + versions reads), createAndUpdateColObjects (object CRUD + revert + bulk), createAndUpdateColGroups (schema CRUD), handleMedia (S3 presign), createAndUpdateIntegrations (integration CRUD + sync + payouts; also dual-mode: handles SQS events for scheduled social posts).

Per-Lambda layout: lambda.js → app.js → api/{index,handlers,controllers} → services/ → models/. Shared logic in src/shared/ via the @shared webpack alias (auditLog.js, contentVersion.js, createApp/createHandler, quota middleware).

Multi-tenant routing — dbKey via the key param

All routes are under /tenant/. CMS reads the tenant DB key from req.query.key (Secure API uses dbKey — don't confuse). await dynamicDb.connect(dbKey) selects the group's database. Always pass it.

mainDb lookups: never { groupName }. active_ctx has only groupID + dbKey. Use { _id: groupID } or { key: dbKey } (here dbKey === group.key).

Adding a route — 8 steps (step 7 = the 403 trap)

1. scripts/validators.js (Joi) → 2. services/myFeature.js → 3. services/index.js → 4. api/controllers/myFeature.js (set req.resData = {status, response}) → 5. api/controllers/index.js → 6. api/index.js (router.{method} via handleTenantRoutes) → 7. cloudformation/<lambda-fragment>.yaml (API Gateway event) → 8. tests (100% coverage gate).

Step 7 is the most-missed. An Express route without the matching SAM event returns 403 (API Gateway doesn't know it, Cognito authorizer never fires). Never edit allRoutes.yaml directly — it's generated by scripts/merge-template.js on build.

Patterns

• Handler wrapper is handleTenantRoutes (older docs say handleHBRoutes — actual export is handleTenantRoutes). Controller sets req.resData.
• Audit logging (src/shared/auditLog.js) — fire-and-forget, lazy Mongoose model registration, 10 controllers instrumented. If it fails the main op still succeeds.
• Content versioning (src/shared/contentVersion.js) — createVersion (auto-increment + tier-based pruning), hooked into create/update/delete; revert via PUT /tenant/collectionObject/revert. Versioning lives ONLY here, not Secure API.
• Integration sync (services/sync/) — provider adapter pattern (collectionName, fetchExternalItems, mapToDocument, getExternalId). bulkWrite upsert keyed on external ID (idempotent). Stripe works immediately; social adapters need OAuth creds (throw MISSING_CREDENTIALS). Called by VR_Secure_API, not the portal directly.
• publishDate: null = draft (hidden from public). Scheduling via EventBridge → SQS FIFO → integrations Lambda.

Gotchas

• arm64 Lambda layers only. An x86_64 layer extension binary crashes at init (Extension.Crash). OTEL collector layer caused this; removed March 2026. FFmpeg layer must also be arm64.
• Nearly zero custom indexes — missing on collectionObjects.refID, .publishDate, sites.groupID.
• Known tech debt: createStripeIntegrationObject.js:118 undefined extra; updateIntegrationObject.js:54 undefined id/bucketName.
• Stripe fulfillment webhook is the one route with Auth: NONE (validates Stripe signature instead).