# profullstack/smshub architecture

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

- Interactive diagram: https://gitdiagram.com/profullstack/smshub
- Repository: https://github.com/profullstack/smshub

## Overview

SMSHub is a multi-platform SMS service: users sign in, manage provider credentials and numbers, then exchange messages in a real-time inbox or through developer interfaces. Its domain also includes rented-number checkout and provisioning, inbound webhooks and delivery outcomes, alerts, teams/groups, and user-configured outbound webhooks. The graph emphasizes documented capabilities and source-visible calls; several web and platform subsystems are represented by their exact directories because their implementation was not sampled, so those links are omitted where evidence is unavailable.

Main entry points: [`src/lib/supabase/server.ts`](https://github.com/profullstack/smshub/blob/master/src/lib/supabase/server.ts) (Supabase data and realtime), [`src/lib/mcp/server.ts`](https://github.com/profullstack/smshub/blob/master/src/lib/mcp/server.ts) (MCP tools), [`src/components/inbox-client.tsx`](https://github.com/profullstack/smshub/blob/master/src/components/inbox-client.tsx) (Unified inbox), [`src/lib/managed-numbers/service.ts`](https://github.com/profullstack/smshub/blob/master/src/lib/managed-numbers/service.ts) (Rental lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Clients"]
  node_web["Web app"]
  node_inbox["Unified inbox<br/>[inbox-client.tsx]"]
  node_mobile["Mobile apps"]
  node_desktop["Desktop app"]
  node_cli["CLI and TUI<br/>[smshub.mjs]"]
end

subgraph group_messaging["Messaging"]
  node_inboxhook["Inbox data hook<br/>[use-inbox.ts]"]
  node_messages["Message API"]
  node_send["Send service<br/>[send.ts]"]
  node_providers["SMS providers<br/>[index.ts]"]
  node_providerext["Twilio and Telnyx"]
  node_inbound["Inbound webhooks"]
  node_delivery["Delivery status<br/>[message-status.ts]"]
end

subgraph group_numbers["Numbers and Providers"]
  node_managed["Rental lifecycle<br/>[service.ts]"]
  node_checkout["Payment checkout<br/>[checkout.ts]"]
  node_telnyx["Telnyx account API<br/>[telnyx-api.ts]"]
  node_numbersapi["Number management API<br/>[route.ts]"]
end

subgraph group_platform["Developer Platform"]
  node_mcp["MCP interface<br/>[route.ts]"]
  node_mcptools["MCP tools<br/>[server.ts]"]
  node_devapi["Developer APIs"]
  node_hooks["Outbound webhooks<br/>[hub.ts]"]
end

subgraph group_services["Account Services"]
  node_db[("Supabase data and realtime<br/>[server.ts]")]
  node_auth["Authentication<br/>[request-user.ts]"]
  node_vault["Key vault<br/>[service.ts]"]
  node_alerts["Alerts<br/>[service.ts]"]
  node_groups["Groups and campaigns<br/>[groups.ts]"]
end

node_user(("SMSHub user"))

node_user -->|"uses"| node_web
node_user -->|"uses"| node_mobile
node_user -->|"uses"| node_desktop
node_user -->|"uses"| node_cli
node_web -.->|"renders"| node_inbox
node_inbox -->|"loads via"| node_inboxhook
node_inbox -.->|"sends through"| node_messages
node_inboxhook -.->|"realtime data"| node_db
node_mobile -.->|"syncs with"| node_db
node_desktop -.->|"realtime updates"| node_db
node_cli -.->|"calls"| node_devapi
node_messages -.->|"delegates to"| node_send
node_send -.->|"sends via"| node_providers
node_providers -->|"dispatches to"| node_providerext
node_inbound -.->|"parses and validates"| node_providers
node_inbound -.->|"records messages"| node_db
node_delivery -->|"formats failures"| node_inbox
node_auth -->|"resolves user"| node_db
node_numbersapi -->|"reads and writes"| node_db
node_numbersapi -->|"opens credentials"| node_vault
node_numbersapi -->|"configures webhooks"| node_telnyx
node_managed -->|"creates checkout"| node_checkout
node_managed -->|"emits events"| node_hooks
node_mcp -->|"resolves caller"| node_auth
node_mcp -->|"dispatches RPC"| node_mcptools
node_mcptools -->|"lists alerts"| node_alerts
node_mcptools -->|"lists webhooks"| node_hooks
node_mcptools -->|"uses number API"| node_managed
node_devapi -.->|"number operations"| node_managed
node_groups -.->|"campaign events"| node_hooks

click node_web "https://github.com/profullstack/smshub/tree/master/src/app"
click node_inbox "https://github.com/profullstack/smshub/blob/master/src/components/inbox-client.tsx"
click node_mobile "https://github.com/profullstack/smshub/tree/master/mobile/app"
click node_desktop "https://github.com/profullstack/smshub/tree/master/electron/src"
click node_cli "https://github.com/profullstack/smshub/blob/master/cli/smshub.mjs"
click node_inboxhook "https://github.com/profullstack/smshub/blob/master/src/hooks/use-inbox.ts"
click node_messages "https://github.com/profullstack/smshub/tree/master/src/app/api/messages"
click node_send "https://github.com/profullstack/smshub/blob/master/src/lib/messages/send.ts"
click node_providers "https://github.com/profullstack/smshub/blob/master/src/lib/providers/index.ts"
click node_providerext "https://github.com/profullstack/smshub/tree/master/src/lib/providers"
click node_inbound "https://github.com/profullstack/smshub/tree/master/src/app/api/webhooks"
click node_delivery "https://github.com/profullstack/smshub/blob/master/src/lib/message-status.ts"
click node_db "https://github.com/profullstack/smshub/blob/master/src/lib/supabase/server.ts"
click node_auth "https://github.com/profullstack/smshub/blob/master/src/lib/request-user.ts"
click node_vault "https://github.com/profullstack/smshub/blob/master/src/lib/vault/service.ts"
click node_managed "https://github.com/profullstack/smshub/blob/master/src/lib/managed-numbers/service.ts"
click node_checkout "https://github.com/profullstack/smshub/blob/master/src/lib/coinpay/checkout.ts"
click node_telnyx "https://github.com/profullstack/smshub/blob/master/src/lib/providers/telnyx-api.ts"
click node_numbersapi "https://github.com/profullstack/smshub/blob/master/src/app/api/phone-numbers/route.ts"
click node_mcp "https://github.com/profullstack/smshub/blob/master/src/app/api/mcp/route.ts"
click node_mcptools "https://github.com/profullstack/smshub/blob/master/src/lib/mcp/server.ts"
click node_devapi "https://github.com/profullstack/smshub/tree/master/src/app/api/v1"
click node_hooks "https://github.com/profullstack/smshub/blob/master/src/lib/webhooks/hub.ts"
click node_alerts "https://github.com/profullstack/smshub/blob/master/src/lib/alerts/service.ts"
click node_groups "https://github.com/profullstack/smshub/blob/master/src/lib/groups.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_web,node_inbox,node_mobile,node_desktop,node_cli,node_user toneBlue
class node_inboxhook,node_messages,node_send,node_providers,node_providerext,node_inbound,node_delivery toneAmber
class node_managed,node_checkout,node_telnyx,node_numbersapi toneMint
class node_mcp,node_mcptools,node_devapi,node_hooks toneRose
class node_db,node_auth,node_vault,node_alerts,node_groups toneIndigo
```

## Components

### User Clients

- [Web app](https://github.com/profullstack/smshub/tree/master/src/app): `src/app`
- [Unified inbox](https://github.com/profullstack/smshub/blob/master/src/components/inbox-client.tsx): `src/components/inbox-client.tsx`
- [Mobile apps](https://github.com/profullstack/smshub/tree/master/mobile/app): `mobile/app`
- [Desktop app](https://github.com/profullstack/smshub/tree/master/electron/src): `electron/src`
- [CLI and TUI](https://github.com/profullstack/smshub/blob/master/cli/smshub.mjs): `cli/smshub.mjs`

### Messaging

- [Inbox data hook](https://github.com/profullstack/smshub/blob/master/src/hooks/use-inbox.ts): `src/hooks/use-inbox.ts`
- [Message API](https://github.com/profullstack/smshub/tree/master/src/app/api/messages): `src/app/api/messages`
- [Send service](https://github.com/profullstack/smshub/blob/master/src/lib/messages/send.ts): `src/lib/messages/send.ts`
- [SMS providers](https://github.com/profullstack/smshub/blob/master/src/lib/providers/index.ts): `src/lib/providers/index.ts`
- [Twilio and Telnyx](https://github.com/profullstack/smshub/tree/master/src/lib/providers): `src/lib/providers`
- [Inbound webhooks](https://github.com/profullstack/smshub/tree/master/src/app/api/webhooks): `src/app/api/webhooks`
- [Delivery status](https://github.com/profullstack/smshub/blob/master/src/lib/message-status.ts): `src/lib/message-status.ts`

### Numbers and Providers

- [Rental lifecycle](https://github.com/profullstack/smshub/blob/master/src/lib/managed-numbers/service.ts): `src/lib/managed-numbers/service.ts`
- [Payment checkout](https://github.com/profullstack/smshub/blob/master/src/lib/coinpay/checkout.ts): `src/lib/coinpay/checkout.ts`
- [Telnyx account API](https://github.com/profullstack/smshub/blob/master/src/lib/providers/telnyx-api.ts): `src/lib/providers/telnyx-api.ts`
- [Number management API](https://github.com/profullstack/smshub/blob/master/src/app/api/phone-numbers/route.ts): `src/app/api/phone-numbers/route.ts`

### Developer Platform

- [MCP interface](https://github.com/profullstack/smshub/blob/master/src/app/api/mcp/route.ts): `src/app/api/mcp/route.ts`
- [MCP tools](https://github.com/profullstack/smshub/blob/master/src/lib/mcp/server.ts): `src/lib/mcp/server.ts`
- [Developer APIs](https://github.com/profullstack/smshub/tree/master/src/app/api/v1): `src/app/api/v1`
- [Outbound webhooks](https://github.com/profullstack/smshub/blob/master/src/lib/webhooks/hub.ts): `src/lib/webhooks/hub.ts`

### Account Services

- [Supabase data and realtime](https://github.com/profullstack/smshub/blob/master/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- [Authentication](https://github.com/profullstack/smshub/blob/master/src/lib/request-user.ts): `src/lib/request-user.ts`
- [Key vault](https://github.com/profullstack/smshub/blob/master/src/lib/vault/service.ts): `src/lib/vault/service.ts`
- [Alerts](https://github.com/profullstack/smshub/blob/master/src/lib/alerts/service.ts): `src/lib/alerts/service.ts`
- [Groups and campaigns](https://github.com/profullstack/smshub/blob/master/src/lib/groups.ts): `src/lib/groups.ts`

### Other components

- **SMSHub user**

## Connections

- SMSHub user → Web app: uses (evidence: `README.md`)
- SMSHub user → Mobile apps: uses (evidence: `README.md`)
- SMSHub user → Desktop app: uses (evidence: `README.md`)
- SMSHub user → CLI and TUI: uses (evidence: `README.md`)
- Web app → Unified inbox: renders
- Unified inbox → Inbox data hook: loads via (evidence: `src/components/inbox-client.tsx`)
- Unified inbox → Message API: sends through
- Inbox data hook → Supabase data and realtime: realtime data
- Mobile apps → Supabase data and realtime: syncs with
- Desktop app → Supabase data and realtime: realtime updates
- CLI and TUI → Developer APIs: calls
- Message API → Send service: delegates to
- Send service → SMS providers: sends via
- SMS providers → Twilio and Telnyx: dispatches to (evidence: `src/lib/providers/index.ts`)
- Inbound webhooks → SMS providers: parses and validates
- Inbound webhooks → Supabase data and realtime: records messages
- Delivery status → Unified inbox: formats failures (evidence: `src/components/inbox-client.tsx`)
- Authentication → Supabase data and realtime: resolves user (evidence: `src/lib/request-user.ts`)
- Number management API → Supabase data and realtime: reads and writes (evidence: `src/app/api/phone-numbers/route.ts`)
- Number management API → Key vault: opens credentials (evidence: `src/app/api/phone-numbers/route.ts`)
- Number management API → Telnyx account API: configures webhooks (evidence: `src/app/api/phone-numbers/route.ts`)
- Rental lifecycle → Payment checkout: creates checkout (evidence: `src/lib/managed-numbers/service.ts`)
- Rental lifecycle → Outbound webhooks: emits events (evidence: `src/lib/managed-numbers/service.ts`)
- MCP interface → Authentication: resolves caller (evidence: `src/app/api/mcp/route.ts`)
- MCP interface → MCP tools: dispatches RPC (evidence: `src/app/api/mcp/route.ts`)
- MCP tools → Alerts: lists alerts (evidence: `src/lib/mcp/server.ts`)
- MCP tools → Outbound webhooks: lists webhooks (evidence: `src/lib/mcp/server.ts`)
- MCP tools → Rental lifecycle: uses number API (evidence: `src/lib/mcp/server.ts`)
- Developer APIs → Rental lifecycle: number operations
- Groups and campaigns → Outbound webhooks: campaign events
