# promptable/twilio-gpt-sms architecture

> Architecture diagram of the GitHub repository promptable/twilio-gpt-sms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/promptable/twilio-gpt-sms
- Repository: https://github.com/promptable/twilio-gpt-sms

## Overview

This is a TypeScript SMS chatbot starter: an incoming Twilio message reaches an Express webhook, which obtains a conversation-aware GPT reply and returns it as TwiML. The main runtime stages are webhook handling, in-memory per-phone conversation state, prompt preparation, external prompt retrieval and completion generation, and SMS response construction. The README documents Twilio setup and optional Promptable prompts; the source also shows the in-memory store and AI call sites. Deployment and build tooling are omitted. Relationships involving Twilio are documented in the README; the sampled source does not show webhook validation.

Main entry points: [`src/gpt3.ts`](https://github.com/promptable/twilio-gpt-sms/blob/main/src/gpt3.ts) (Reply Orchestrator), [`routes/messages.ts`](https://github.com/promptable/twilio-gpt-sms/blob/main/routes/messages.ts) (Message Handler), [`index.ts`](https://github.com/promptable/twilio-gpt-sms/blob/main/index.ts) (HTTP Server), [`server.ts`](https://github.com/promptable/twilio-gpt-sms/blob/main/server.ts) (Express App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_webhook["SMS Webhook"]
  node_entry["HTTP Server<br/>[index.ts]"]
  node_server["Express App<br/>[server.ts]"]
  node_messages["Message Handler<br/>[messages.ts]"]
  node_request["Webhook Request Type<br/>[request.ts]"]
  node_config["Port Configuration<br/>[config.ts]"]
end

subgraph group_conversation["Conversation Runtime"]
  node_reply["Reply Orchestrator<br/>[gpt3.ts]"]
  node_history["Chat History Store<br/>[chatHistory.ts]"]
  node_prompt_prep["Prompt Preparation<br/>[gpt3.ts]"]
end

subgraph group_ai["AI Services"]
end

node_sms_user(("SMS Sender"))
node_twilio["Twilio Messaging"]
node_promptable["Promptable Deployment"]
node_openai["OpenAI Completion"]

node_sms_user -->|"sends SMS"| node_twilio
node_twilio -->|"posts webhook"| node_messages
node_entry -->|"starts"| node_server
node_entry -->|"reads port"| node_config
node_server -->|"mounts route"| node_messages
node_messages -->|"types request"| node_request
node_messages -->|"requests reply"| node_reply
node_reply -->|"reads and updates"| node_history
node_reply -->|"formats prompt"| node_prompt_prep
node_reply -->|"fetches deployment"| node_promptable
node_reply -->|"requests completion"| node_openai
node_messages -->|"returns TwiML"| node_twilio

click node_entry "https://github.com/promptable/twilio-gpt-sms/blob/main/index.ts"
click node_server "https://github.com/promptable/twilio-gpt-sms/blob/main/server.ts"
click node_messages "https://github.com/promptable/twilio-gpt-sms/blob/main/routes/messages.ts"
click node_request "https://github.com/promptable/twilio-gpt-sms/blob/main/types/request.ts"
click node_config "https://github.com/promptable/twilio-gpt-sms/blob/main/config.ts"
click node_reply "https://github.com/promptable/twilio-gpt-sms/blob/main/src/gpt3.ts"
click node_history "https://github.com/promptable/twilio-gpt-sms/blob/main/src/chatHistory.ts"
click node_prompt_prep "https://github.com/promptable/twilio-gpt-sms/blob/main/src/gpt3.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_server,node_messages,node_request,node_config toneBlue
class node_reply,node_history,node_prompt_prep toneAmber
class node_sms_user,node_twilio,node_promptable,node_openai toneIndigo
```

## Components

### SMS Webhook

- [HTTP Server](https://github.com/promptable/twilio-gpt-sms/blob/main/index.ts): `index.ts`
- [Express App](https://github.com/promptable/twilio-gpt-sms/blob/main/server.ts): `server.ts`
- [Message Handler](https://github.com/promptable/twilio-gpt-sms/blob/main/routes/messages.ts): `routes/messages.ts`
- [Webhook Request Type](https://github.com/promptable/twilio-gpt-sms/blob/main/types/request.ts): `types/request.ts`
- [Port Configuration](https://github.com/promptable/twilio-gpt-sms/blob/main/config.ts): `config.ts`

### Conversation Runtime

- [Reply Orchestrator](https://github.com/promptable/twilio-gpt-sms/blob/main/src/gpt3.ts): `src/gpt3.ts`
- [Chat History Store](https://github.com/promptable/twilio-gpt-sms/blob/main/src/chatHistory.ts): `src/chatHistory.ts`
- [Prompt Preparation](https://github.com/promptable/twilio-gpt-sms/blob/main/src/gpt3.ts): `src/gpt3.ts`

### Other components

- **SMS Sender**
- **Twilio Messaging**
- **Promptable Deployment**
- **OpenAI Completion**

## Connections

- SMS Sender → Twilio Messaging: sends SMS (evidence: `README.md`)
- Twilio Messaging → Message Handler: posts webhook (evidence: `README.md`)
- HTTP Server → Express App: starts (evidence: `index.ts`)
- HTTP Server → Port Configuration: reads port (evidence: `index.ts`)
- Express App → Message Handler: mounts route (evidence: `server.ts`)
- Message Handler → Webhook Request Type: types request (evidence: `routes/messages.ts`)
- Message Handler → Reply Orchestrator: requests reply (evidence: `routes/messages.ts`)
- Reply Orchestrator → Chat History Store: reads and updates (evidence: `src/gpt3.ts`)
- Reply Orchestrator → Prompt Preparation: formats prompt (evidence: `src/gpt3.ts`)
- Reply Orchestrator → Promptable Deployment: fetches deployment (evidence: `src/gpt3.ts`)
- Reply Orchestrator → OpenAI Completion: requests completion (evidence: `src/gpt3.ts`)
- Message Handler → Twilio Messaging: returns TwiML (evidence: `README.md`)
