Master replication playbook

Living document · owner Elena, CTO & CSIO · updated 30 October 2026. Every build is logged here and in the platform build doc for that surface, in the same delivery.

Standing rule

Every change gets five things in one delivery: an entry in this playbook with the replicable pattern and the lesson; an entry in the platform build doc for that surface; a post in the portal; the live surface actually updated; and the desk row where that surface appears on a desk. If it is not in both documents, it did not happen.

Entry 001 — Meetings platform

Surface: meet.cjbestinvestments.com · service cjbest-meetings · port 3100 · nginx front

Replicable build sequence

  1. Room page on the Amazon Chime SDK browser bundle. Guest join is two steps: POST /api/rooms/:code/consent returns a receiptId, then POST /api/rooms/:code/guest with that receipt. No receipt means 403 consent_declined.
  2. Room codes are stored lowercase. The client lowercases; the server matches either case. Never uppercase API paths.
  3. Chat, notes and state are server-held: GET/POST /api/rooms/:code/chat, /notes, and GET /api/rooms/:code/state which returns the ended flag and the file list. Attendees poll state every 6 seconds; that is what makes host End propagate and chat broadcast.
  4. Recording: the local MediaRecorder stream uploads to POST /api/rooms/:code/recording (express.raw), transcript lines follow to /transcript.
  5. Transcription is asynchronous: upload to S3, start a Transcribe job with language identification, and have the poller read s3://bucket/transcripts/<id>.json by deterministic key.
  6. Translation per caption line and per transcript via AWS Translate. Source auto requires comprehend:DetectDominantLanguage; without it translation silently returns empty.
  7. mp4 output: static ffmpeg, libx264 with -movflags +faststart, served as video/mp4 so iPhone Safari can play. Share page prefers mp4, falls back to webm.
  8. Recap email on transcript completion: overview, notes, transcript, translation and replay link, from contact@ via SES, logged per recording and address so nothing duplicates.
  9. Navigation standard: Back and Menu on every page, Home where relevant, hub at /menu.
  10. Reports: index plus per-document pages with Download and Print/Save as PDF, A4 print CSS, navigation hidden when printing.
Lesson: consent then guest, lowercase room codes, deterministic transcript key. All three defects today traced to those three points.

Entry 002 — CJ Best Business Suite

Surface: suite.cjbestinvestments.com · code /opt/cjbest-suite · port 8898
  1. Agent API guarded by SUITE_AGENT_KEY: /api/agent/ping, /api/import (skips UNVERIFIED rows with no email), /api/outreach, /api/inbox/send (three approved senders), /api/comms. 401 without the key.
  2. /library groups offering, features and translations, each title opening the real file at /files/<name>.
  3. Delegated click handlers must read attributes from the element variable, never this.
Lesson: append Flask routes at module level before the __main__ guard, always ast.parse before restart, curl health after, and roll back automatically when health is not 200. Two 502s today came from indentation on an appended block.

Entry 003 — Accounting e-sign

Surface: accounting.cjbestinvestments.com
  1. Signature records were storing absolute server paths in file_stored, and some held no file at all, so opening a document 404'd. Repair: normalise to basename, copy the source into sign_files, set the extension. Six of nine repaired.
Lesson: store file names, never absolute paths, and check the file exists before issuing a signing link.