# sexyjaeseok/callprotocall architecture

> Architecture diagram of the GitHub repository sexyjaeseok/callprotocall, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sexyjaeseok/callprotocall
- Repository: https://github.com/sexyjaeseok/callprotocall

## Overview

CallProtocol is an accessible AI-assisted calling service: users submit a call request, answer any follow-up questions, review and approve a plan, then conduct a call with live captions and text-based intervention. The server provides authentication, REST and WebSocket sessions, and scheduled calling; records and reservations persist in SQLite. README documents browser-based ElevenLabs voice calls, optional Twilio phone calls, and simulation fallback. Unsampled UI and API behavior is included only where documented; edges reflect shown calls or README relationships.

Main entry points: [`app/api.py`](https://github.com/sexyjaeseok/callprotocall/blob/main/app/api.py) (REST handlers), [`server.py`](https://github.com/sexyjaeseok/callprotocall/blob/main/server.py) (HTTP server), [`app/ai_engine.py`](https://github.com/sexyjaeseok/callprotocall/blob/main/app/ai_engine.py) (Plan and simulation), [`app/db.py`](https://github.com/sexyjaeseok/callprotocall/blob/main/app/db.py) (SQLite persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Accessible calling UI"]
  node_ui["Web app<br/>[app.v8.js]"]
end

subgraph group_server["Server and sessions"]
  node_http["HTTP server<br/>[server.py]"]
  node_ws["WebSocket transport<br/>[websocket.py]"]
  node_api["REST handlers<br/>[api.py]"]
  node_scheduler["Scheduled calls<br/>[server.py]"]
end

subgraph group_planning["Call planning"]
  node_planning["Plan and simulation<br/>[ai_engine.py]"]
end

subgraph group_records["Accounts and records"]
  node_auth["Authentication<br/>[auth.py]"]
  node_store[("SQLite persistence<br/>[db.py]")]
end

subgraph group_integrations["Voice integrations"]
  node_eleven{{"ElevenLabs voice agent"}}
  node_twilio{{"Twilio phone service"}}
  node_openai["OpenAI wrapper<br/>[llm.py]"]
end

node_user(("Caller"))

node_user -->|"submits requests"| node_ui
node_ui -->|"calls REST"| node_http
node_http -->|"routes requests"| node_api
node_http -->|"checks sessions"| node_auth
node_http -->|"serves sessions"| node_ws
node_api -->|"authenticates users"| node_auth
node_api -->|"builds plans"| node_planning
node_api -->|"reads and writes"| node_store
node_auth -->|"reads and writes"| node_store
node_ws -->|"loads and saves calls"| node_store
node_ws -->|"runs simulation"| node_planning
node_http -->|"starts scheduler"| node_scheduler
node_scheduler -->|"checks reservations"| node_store
node_scheduler -->|"simulates calls"| node_planning
node_ui -->|"streams voice"| node_eleven
node_api -->|"configures calls"| node_eleven
node_api -.->|"initiates phone calls"| node_twilio
node_planning -.->|"may use model"| node_openai

click node_ui "https://github.com/sexyjaeseok/callprotocall/blob/main/web/app.v8.js"
click node_http "https://github.com/sexyjaeseok/callprotocall/blob/main/server.py"
click node_ws "https://github.com/sexyjaeseok/callprotocall/blob/main/app/websocket.py"
click node_api "https://github.com/sexyjaeseok/callprotocall/blob/main/app/api.py"
click node_auth "https://github.com/sexyjaeseok/callprotocall/blob/main/app/auth.py"
click node_store "https://github.com/sexyjaeseok/callprotocall/blob/main/app/db.py"
click node_planning "https://github.com/sexyjaeseok/callprotocall/blob/main/app/ai_engine.py"
click node_scheduler "https://github.com/sexyjaeseok/callprotocall/blob/main/server.py"
click node_openai "https://github.com/sexyjaeseok/callprotocall/blob/main/app/llm.py"

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_ui toneBlue
class node_http,node_ws,node_api,node_scheduler toneAmber
class node_planning toneMint
class node_auth,node_store toneRose
class node_eleven,node_twilio,node_openai,node_user toneIndigo
```

## Components

### Accessible calling UI

- [Web app](https://github.com/sexyjaeseok/callprotocall/blob/main/web/app.v8.js): `web/app.v8.js`

### Server and sessions

- [HTTP server](https://github.com/sexyjaeseok/callprotocall/blob/main/server.py): `server.py`
- [WebSocket transport](https://github.com/sexyjaeseok/callprotocall/blob/main/app/websocket.py): `app/websocket.py`
- [REST handlers](https://github.com/sexyjaeseok/callprotocall/blob/main/app/api.py): `app/api.py`
- [Scheduled calls](https://github.com/sexyjaeseok/callprotocall/blob/main/server.py): `server.py`

### Call planning

- [Plan and simulation](https://github.com/sexyjaeseok/callprotocall/blob/main/app/ai_engine.py): `app/ai_engine.py`

### Accounts and records

- [Authentication](https://github.com/sexyjaeseok/callprotocall/blob/main/app/auth.py): `app/auth.py`
- [SQLite persistence](https://github.com/sexyjaeseok/callprotocall/blob/main/app/db.py): `app/db.py`

### Voice integrations

- **ElevenLabs voice agent**
- **Twilio phone service**
- [OpenAI wrapper](https://github.com/sexyjaeseok/callprotocall/blob/main/app/llm.py): `app/llm.py`

### Other components

- **Caller**

## Connections

- Caller → Web app: submits requests (evidence: `README.md`)
- Web app → HTTP server: calls REST (evidence: `web/app.v8.js`)
- HTTP server → REST handlers: routes requests (evidence: `server.py`)
- HTTP server → Authentication: checks sessions (evidence: `server.py`)
- HTTP server → WebSocket transport: serves sessions (evidence: `server.py`)
- REST handlers → Authentication: authenticates users (evidence: `app/api.py`)
- REST handlers → Plan and simulation: builds plans (evidence: `app/api.py`)
- REST handlers → SQLite persistence: reads and writes (evidence: `app/api.py`)
- Authentication → SQLite persistence: reads and writes (evidence: `app/auth.py`)
- WebSocket transport → SQLite persistence: loads and saves calls (evidence: `server.py`)
- WebSocket transport → Plan and simulation: runs simulation (evidence: `server.py`)
- HTTP server → Scheduled calls: starts scheduler (evidence: `server.py`)
- Scheduled calls → SQLite persistence: checks reservations (evidence: `server.py`)
- Scheduled calls → Plan and simulation: simulates calls (evidence: `server.py`)
- Web app → ElevenLabs voice agent: streams voice (evidence: `README.md`)
- REST handlers → ElevenLabs voice agent: configures calls (evidence: `app/api.py`)
- REST handlers → Twilio phone service: initiates phone calls (evidence: `README.md`)
- Plan and simulation → OpenAI wrapper: may use model
