# Unique Vapors — Senior Architect Brief *(Confidential)*
**Updated:** October 15, 2025 — America/New_York
We’ve built a real multi-surface delivery platform over 40+ weeks — web PWA + Telegram Mini App + role-based dashboards — wired to Neon Postgres, Redis/Bull queues, secure webhooks, and a Sheets mirror. We’re in the last **5–10%** to GA. This brief is **what we are**, **what’s left**, and **who we’ll hire** to land it… cleanly, safely, fast.
---
## 1) What this is (in one breath)
A production-grade, age‑gated commerce & delivery stack targeting Uber‑Eats‑level polish: React 18 PWA, Telegram Mini App, Node 20 Express API, Stripe/PayPal/Solana payments, real‑time dispatch via Socket.IO, strict CSP, and an ops‑friendly Google Sheets mirror. Everything is typed, observable, and built to ship… not a demo.
---
## 2) System snapshot
- **Language mix (≈1.96M LOC workspace)**: JavaScript (~27%), JSON (~22%), TypeScript (~15%), HTML (~11%), TSX (~4%) → primarily typed React/Node with significant build metadata.
- **Runtime**: Node.js ≥ 20.11 (ESM), consistent with Render’s Node 20 target.
- **Front‑end**: React 18, React Router 7, Tailwind 4, Framer Motion, Radix UI; route-level code‑split via Vite; service worker with offline shell.
- **Back‑end**: Express 5 on Node 20, modular routers, strict CSP/Helmet, rate limiting, Sentry hooks, Pino‑style logging; Socket.IO 4 for realtime; Prometheus metrics.
- **Data**: Neon Postgres via Drizzle ORM (typed schema & migrations), search vectors, idempotency tables; nightly `pg_dump` backups; retention jobs.
- **Queues**: Redis‑backed Bull for webhooks & async jobs (safe in‑memory fallback in dev).
- **Payments**: Stripe 17, PayPal REST SDKs, Apple Pay, Solana flows; HMAC/signature, timestamp, idempotency, & duplicate suppression are in place.
- **Integrations**: Shippo, Google Maps (MapID), Google Sheets mirror, Sentry; Web Push (VAPID).
- **Channels & surfaces**: Web SPA/PWA (served from `/public`), Telegram Mini App, Admin/Vendor/Driver/Support dashboards, push notifications, cron exports.
- **Hosting targets**: Render (primary) + Railway (alt) with health probes (`/healthz`, `/readyz`) & automated migrations.
---
## 3) Architecture — current vs. target
**Current**: Single Node 20 app serves API, static, webhooks, and Socket.IO; queues offload Stripe/PayPal/Telegram events; health endpoints compose DB/Redis/Sheets/Payments states; service worker precaches shell & images; strict CSP with only required origins.
**Target uplifts (no rewrites, just hardening)**:
- **Isolate webhooks** into a dedicated worker tier & **promote Redis to managed TLS cluster**.
- Put **CDN/WAF** in front of SPA/API with immutable cache headers for `/assets` & smart cache keys.
- **Observability**: Prometheus/Grafana + Sentry + trace sampling; RED/SLA panels for API, webhooks, Sheets sync.
- **Object store** for exports & receipts (encrypted) → decouple from app disk.
- Lock **CI gates** on route manifest parity, Lighthouse budgets, and secret scans.
---
## 4) Where we stand (honest “Amber”)
- **Secrets parity**: Rotate/validate Sheets service account, Stripe/PayPal/Solana webhook secrets; ensure `REDIS_URL` points to managed cluster.
- **Readiness & static**: Eliminate `/` & asset 404s during readiness by serving `/assets` with immutable headers & explicit `index.html` route.
- **Route manifest drift**: Regenerate per‑route bundles; fix SPA fallback forcing `index.html` for all routes.
- **PWA offline smoke**: Re‑enable headless deps in CI; confirm cache hits for critical routes.
- **CI stability**: Ensure `suite:run` green (lint + tsc + tests + route parity + Lighthouse).
- **Webhook receipts**: Archive 2xx replays for Stripe/PayPal/Telegram in `evidence/` (idempotency table proves duplicates are suppressed).
- **Sheets mirror**: Commission with valid creds; produce first dry‑run log & row counts.
---
## 5) The person we will hire (non‑negotiable)
**A senior platform architect/engineer who’s shipped complex systems *before* the AI era & still ships today.**
- **10–15+ years** building & operating production platforms (payments, regulated commerce, or logistics).
- **Stack fluency**: TypeScript/Node 20, Express 5, React 18/Vite, Drizzle + Postgres (Neon), Redis/Bull, Stripe/PayPal, Telegram (webhooks + Mini App), Google Sheets API, Web Push.
- **Security & compliance**: CSP that actually passes, HMAC/signatures, rate limits, audit logging, idempotent webhooks, secret rotation.
- **Operational muscle**: CI/CD on GitHub Actions, evidence‑driven launches, rollback plans, RED/SLO thinking, on‑call habits.
- **Taste**: Bespoke UI… no templates, no placeholders. Understands LCP/CLS/INP & how to hit them on mobile 4G.
Nice‑to‑haves: Solana payouts, Apple Pay, Shippo, Prometheus/Grafana, Sentry, Terraform; SOC2/PCI exposure.
---
## 6) Last 5–10% to GA (discreet but complete)
1. **Secrets & Redis** — rotate Sheets/Stripe/PayPal/Solana; wire managed Redis (TLS).
2. **Static readiness** — serve `/assets` immutably; ensure `/` & `/index.html` deliver; remove 404s.
3. **Route manifest** — reinstate per‑route code‑split; fix SPA fallback to stop index‑for‑everything.
4. **PWA smoke** — headless deps in CI; verify offline shell & cache strategies on key routes.
5. **Webhooks** — 2xx receipts archived for Stripe/PayPal/Telegram; monitor duplicate suppression.
6. **Sheets mirror** — enable `SHEETS_SYNC_ENABLED`, run dry‑run & full sync, attach receipts.
7. **CDN/WAF** — cache keys for SPA, enforce minimal origins; confirm CSP stays strict.
8. **Observability** — dashboards for API/webhooks/Sheets; alerts on RED/SLA thresholds.
9. **Push** — load VAPID keys; exercise subscription flow; add queue latency alerts.
10. **QA pass** — role‑gated route sweep (admin/vendor/driver/customer/support) with videos & a11y.
**Acceptance =** green CI + Lighthouse budgets (LCP < 2.5s, CLS < 0.1, INP < 200ms), webhook receipts archived, Sheets sync proof, health/ready 200s, CSP report clean, rollback test performed.
---
## 7) 30–60–90 (outcomes, not theatrics)
- **30 days** → Secrets parity, Redis cluster, static readiness fixed, route manifest stabilized, CI green; first evidence packet uploaded.
- **60 days** → Dedicated webhook worker tier, CDN/WAF live, PWA offline validated, dashboards/alerts wired; Stripe/PayPal/Telegram receipts on schedule.
- **90 days** → Sheets mirror fully operational with replay plan, RED/SLOs tracked, push telemetry live, rollback & drill runbooks validated, GA ready.
---
## 8) Risks & mitigations (shortlist)
- **Plaintext secret sprawl** → add secret‑scan gate (gitleaks) & rotate everything; ban backup dirs from repo.
- **Redis fallback in prod** → enforce TLS cluster URL at boot; fail‑fast if missing.
- **Route fallback bloat** → test route parity in CI; budget‑gate on bundle size & LCP.
- **Webhooks under load** → queue depth/latency alerts; idempotency table proves duplicate drops.
- **Sheets drift** → lag metric + alert; dry‑run receipts required daily.
---
## 9) Evidence we expect day‑one (Repo Audit Kit included)
- `/api/health` + `/api/ready` curls (200), version stamp.
- Stripe/PayPal/Telegram webhook replay receipts (2xx) & idempotency counts.
- Lighthouse + PWA offline receipts (screenshots/JSON).
- Sheets dry‑run + sync log; row count diffs.
- Route manifest parity snapshot; bundle sizes.
- RED dashboards screenshots (API/webhooks/Sheets).
---
## 10) COPY‑ALL — terminal quick start (macOS + zsh)
```bash
# essentials
brew install fzf fd ripgrep bat eza zoxide git jq gitleaks semgrep syft trivy
# unpack the Repo Audit Kit at repo root
unzip -o "repo-audit-kit.zip" -d ./
# run the turnkey audit locally (safe: reads repo, writes audit_out/)
bash repo-audit-kit/audit.sh
# minimal app smoke (adjust port/env in your project)
node -v
npm -v
npm ci
npm run build:client
# curl health endpoints (customize base URL)
curl -sS http://localhost:5000/api/health | jq . >/dev/null
curl -sS http://localhost:5000/api/ready | jq . >/dev/null
```
---
### One‑liner “how to use”
**Hand this brief + the Repo Audit Kit to the senior architect; ask for a 7‑day hardening plan, evidence pack links, & a go/no‑go date.** No placeholders. No regressions. Only upgrades.