# Twilio Architecture Reference
**Cold Bore Ballistics LLC — Confidential**
Last updated: 2026-06-06
Status: Active — IVR deployed and live on 1-877-DOPE-707

> This document is the authoritative record of what exists in the CBB Twilio account. It is the single source of truth for resource names, SIDs, and configuration state. Never duplicate this information in other documents — cross-reference here instead.

---

## Account Structure

### Organization

| Field | Value |
|---|---|
| **Organization name** | Cold Bore Ballistics LLC |
| **Organization SID** | `ORa717cfdd49f8400b877c7ca212f1dfb1` |
| **Status** | Active |

### Parent Account — CBB Corporate

| Field | Value |
|---|---|
| **Account name** | CBB Corporate |
| **Account SID** | `AC26cc215c2e2f0425984bffbe7050a0e0` |
| **Region** | United States (US1) |
| **Status** | Active |
| **Account type** | Full (upgraded, pre-funded) |
| **Balance at setup** | $50.00 |
| **Created** | 2026-06-05 |
| **Purpose** | 800 number, caller ID masking, corporate SMS, feedback-service notifications, service alerting |

### Subaccount — ScopeDOPE

| Field | Value |
|---|---|
| **Account name** | ScopeDOPE |
| **Account SID** | `AC7cc6b6571c9b0907b73b783a5422a2c4` |
| **Owner** | `AC26cc215c2e2f0425984bffbe7050a0e0` (CBB Corporate) |
| **Status** | Active |
| **Created** | 2026-06-05 |
| **Purpose** | ScopeDOPE app support SMS, two-way support channel, future in-app notifications |

> **Billing:** All subaccount charges consolidate to the CBB Corporate parent account balance.
>
> **Future subaccounts:** Create when a new product line actively requires Twilio resources — do not create placeholders.

---

## Credentials

### Primary Auth Token
| Field | Value |
|---|---|
| **Usage** | Root credential — use only for account-level operations and emergency access |
| **Location** | OneDrive/03_-_Confidential/Infrastructure/Twilio/ (credentials reference) |
| **Rotation policy** | Rotate only if compromised — rotation invalidates ALL API keys |

> **WARNING:** Never use the Auth Token in application code. Use API Keys instead.

### API Keys — CBB Corporate

| Friendly name | SID | Secret location | Type | Created | Purpose |
|---|---|---|---|---|---|
| `claude-code-cli` | `SK0974f8802be51c9c2e6fec7a4455b2cf` | `kv-cbb-shared-prod` → `twilio-cbb-claude-code-cli-secret` | Standard | 2026-06-06 | Operator/CLI account management |

> API Key secrets are stored in Azure Key Vault. See `Azure_Key_Vault_Architecture_Reference.md` for the secret inventory and Operating Runbook for key rotation procedure.

### Auth Tokens

| Account | Secret location | Notes |
|---|---|---|
| CBB Corporate | `kv-cbb-shared-prod` → `twilio-cbb-auth-token` | Primary auth token — root credential, use only for account-level operations and emergency access. Never use in application code |
| ScopeDOPE | `kv-scope-dope-prod` → `twilio-scopedope-auth-token` | Shown once at subaccount creation. Use subaccount-specific API keys for all ScopeDOPE application calls — never use the auth token in code |

> **WARNING:** Never use Auth Tokens in application code. Create account-specific API Keys for each integration.

---

## Address

| Field | Value |
|---|---|
| **SID** | `ADd19f0b897a18a3dd58bb5bd8f6ba279f` |
| **Friendly name** | Cold Bore Ballistics LLC - Primary |
| **Customer name** | Cold Bore Ballistics LLC |
| **Street** | 209 Oakland Avenue |
| **City** | Mukwonago |
| **State** | WI |
| **Postal code** | 53149 |
| **Country** | US |
| **Validated** | Yes (by Twilio at signup) |
| **Emergency enabled** | No (not required for SMS/non-voice use) |

---

## Phone Numbers

| Friendly name | Number | E.164 | SID | Account | Role | Purchased |
|---|---|---|---|---|---|---|
| CBB Corporate - 855-COLD-390 | 1-855-COLD-390 | `+18552653390` | `PNa59360923ca4ba0d48c5bc15d617955d` | CBB Corporate | Primary CBB corporate brand number — voice/SMS | 2026-06-05 |
| ScopeDOPE - 877-DOPE-707 | 1-877-DOPE-707 | `+18773673707` | `PNc79962bd2498db160604d8ce6fb1e4f7` | ScopeDOPE | **Primary ScopeDOPE number** — UC-01 inbound voice/SMS, app support, marketing; wired to ScopeDOPE IVR Studio flow | 2026-06-05 |

> **Voice configuration on 877-DOPE-707:** Wired to Studio flow `ScopeDOPE IVR` (`FW2e741d9b3c95f44fe571ff182b987873`) — see IVR & Voicemail section below.

---

## IVR & Voicemail

### Studio Flow — ScopeDOPE IVR

| Field | Value |
|---|---|
| **Flow name** | ScopeDOPE IVR |
| **Flow SID** | `FW2e741d9b3c95f44fe571ff182b987873` |
| **Status** | Published |
| **Wired to** | `+18773673707` (ScopeDOPE - 877-DOPE-707) |
| **Deployed** | 2026-06-06 |

### Twilio Function — ivr-voicemail-handler

| Field | Value |
|---|---|
| **Service SID** | `ZSfb518af22cef2c341dccd311a4d29d81` |
| **Function SID** | `ZHe3a5e928e7fb1b1e01fbbc1f1e41db3b` |
| **Environment SID** | `ZEa0ad80e6327ffb7bb3a3bb31db28469c` |
| **Function URL** | `https://ivr-voicemail-handler-6661-prod.twil.io/voicemail` |
| **Runtime** | node22 |
| **Dependency** | `@sendgrid/mail@8.1.3` |
| **Env var: SENDGRID_API_KEY** | SendGrid `twilio-ivr` key — value in `kv-cbb-shared-prod` → `sendgrid-twilio-ivr-secret` |
| **Env var: FROM_EMAIL** | `noreply@scope-dope.com` |

### Voicemail Routing Map

| Caller presses | Category | Subject prefix | To address | X-CBB-Option |
|---|---|---|---|---|
| 1 | Bug report | `[Bug Report]` | `phone@scope-dope.com` | `1` |
| 2 | Feature request | `[Feature Request]` | `phone@scope-dope.com` | `2` |
| 3 | General support | `[Support]` | `phone@scope-dope.com` | `3` |
| 4 | Business inquiry | `[Business Inquiry]` | `phone@coldboreballisticsllc.com` | `4` |
| 9 → 1 (or timeout) | ScopeDOPE general | `[ScopeDOPE General]` | `phone@scope-dope.com` | `9-1` |
| 9 → 2 | CBB general | `[CBB General]` | `phone@coldboreballisticsllc.com` | `9-2` |

**Navigation:** Press 0 repeats current menu. Press * returns to main menu from any level. Voicemail max: 120 seconds.

**Email headers on all voicemails:** `X-CBB-Source: twilio-ivr`, `X-CBB-Called: +18773673707`, `X-CBB-Category: <category>`, `X-CBB-Option: <option>`

---

## Messaging Services

| Field | Value |
|---|---|
| **Friendly name** | Cold Bore Ballistics LLC - Primary |
| **SID** | `MGfed49ffbd4095c927e22b49670b0a48d` |
| **Region** | US1 |
| **Sticky sender** | Enabled — messages from same number to same recipient |
| **Smart encoding** | Enabled — auto-detects Unicode, downgrades to GSM-7 where possible |
| **Area code geomatch** | Enabled — selects sender number matching recipient area code |
| **Fallback to long code** | Enabled |
| **MMS converter** | Enabled |
| **Validity period** | 14,400 seconds (4 hours) |
| **A2P 10DLC registered** | No — required before production SMS volume |
| **Use case** | Undeclared — update when 10DLC registration is complete |
| **Created** | 2026-06-05 |

---

## SendGrid

SendGrid is a separate infrastructure domain — see `OneDrive/CBB_Corporate/03_-_Confidential/Infrastructure/SendGrid/SendGrid_Architecture_Reference.md`.

---

## Subaccounts

See Account Structure section above. ScopeDOPE subaccount (`AC7cc6b6571c9b0907b73b783a5422a2c4`) is active under CBB Corporate. No phone numbers or messaging services provisioned on the subaccount yet.

---

## 10DLC Registration

*Not yet registered. See CBB-103.*

**Two-step process — brand first, then campaign:**

1. **Brand registration** (CBB-103) — registers Cold Bore Ballistics LLC as a verified sender with US carriers. One-time $4.00 fee. Must be approved before campaign can be registered.
2. **Campaign registration** — registers the specific SMS use case (content type, sample messages). $15.00/month per campaign. Execute only after brand is approved. Campaign must be linked to the relevant Messaging Service before production SMS can be sent.

Do not send production A2P SMS volume before both steps are complete.

---

## Verified Caller IDs

*None configured yet.*

---

## Compliance

| Item | Status | Notes |
|---|---|---|
| A2P 10DLC brand registration | Not started | Required before Club SaaS SMS (UC-05, UC-08) |
| A2P 10DLC campaign registration | Not started | $15/month per campaign; execute before Club SaaS goes live |
| TCPA opt-out handling | Not started | Handled automatically by Twilio Messaging Services |
| GDPR/CCPA consent records | Not started | Required at phone number collection points |

---

## Cost Tracking

| Resource | Monthly cost | Notes |
|---|---|---|
| Account | $0 | Pay-as-you-go |
| Messaging Service | $0 | No cost until messages sent through it |
| 855-COLD-390 toll-free (CBB Corporate) | ~$2.00 | CBB corporate brand number — purchased 2026-06-05 |
| 877-DOPE-707 toll-free (ScopeDOPE) | ~$2.00 | ScopeDOPE primary number — purchased 2026-06-05 |
| SendGrid free tier | $0 | Up to 100 emails/day — see SendGrid_Architecture_Reference.md |
| Twilio Functions (ivr-voicemail-handler) | $0 | Free tier: 10,000 invocations/month included |
| Twilio Studio (ScopeDOPE IVR) | ~$0.01/execution | $0.01 per active user flow execution; negligible at current volume |
| Transcription | ~$0.10/voicemail max | $0.05/minute; 120-second max = $0.10 per voicemail |
| **Current total** | **~$4.00/month** | Two toll-free numbers; IVR costs negligible at launch volume |

---

## Console Settings

| Setting | Value | Status |
|---|---|---|
| Timezone | America/Chicago | Configured 2026-06-05 |
| Profile name | Jason Schwefel | Configured 2026-06-05 |
| 2FA | Enabled | CBB-99 Done |

---

## Change Management

Before making any change to the Twilio account (purchasing a number, editing the IVR, rotating a key), run a snapshot and commit it:

```bash
cd cbb-utils/twilio
./snapshot_account.sh
git add twilio_snapshot_*.zone
git commit -m "snapshot: before <describe your change>"
```

The snapshot zone files live in `cbb-utils/twilio/`. The commit message records the pre-change state and what was about to change.

---

## Architecture Decisions

| Decision | Choice | Rationale |
|---|---|---|
| Auth model | API Keys (not Auth Token) | Scoped, revocable; Auth Token rotation invalidates all keys |
| Account structure | Parent + subaccounts per product line | Clean cost separation for acquisition due diligence; CBB Corporate is parent |
| Region | US1 | CBB is US-based; all target markets domestic |
| SMS compliance path | A2P 10DLC (not short code) | Cost-appropriate for launch scale; short codes at significant volume if warranted |
| Subaccount creation policy | Create when product line is active — no placeholders | Avoids noise; subaccounts added as Club SaaS, Gunsmith SaaS, etc. are built |

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (03_-_Confidential/) |
| **Location** | `OneDrive/CBB_Corporate/03_-_Confidential/Infrastructure/Twilio/Twilio_Architecture_Reference.md` |
| **Cross-references** | `Twilio_Operating_Runbook.md`; `Twilio_Rebuild_Guide.md`; `Twilio_Acquisition_Brief.md`; `SendGrid_Architecture_Reference.md` |
| **Created** | 2026-06-06 |
| **Last updated** | 2026-06-06 |
| **Next full review due** | 2027-06-06 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| 0.9 | 2026-06-06 | jschwefel | — | — | Initial release |
