# knadh/otpgateway architecture

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

- Interactive diagram: https://gitdiagram.com/knadh/otpgateway
- Repository: https://github.com/knadh/otpgateway

## Overview

OTP Gateway is a standalone, multi-tenant service for initiating address-verification challenges, delivering codes through configurable providers, and checking verification status. Clients can use authenticated HTTP/JSON APIs or the built-in web flow, including its JavaScript modal; users may enter an address when one was not supplied. Redis stores challenge state and attempts. The graph reflects the sampled routing, initialization, handler, and provider code plus README capabilities; unsampled view and handler details are represented conservatively.

Main entry points: [`cmd/otpgateway/handlers.go`](https://github.com/knadh/otpgateway/blob/master/cmd/otpgateway/handlers.go) (OTP API and flow handlers), [`cmd/otpgateway/main.go`](https://github.com/knadh/otpgateway/blob/master/cmd/otpgateway/main.go) (HTTP server and routes), [`cmd/otpgateway/init.go`](https://github.com/knadh/otpgateway/blob/master/cmd/otpgateway/init.go) (Provider initialization), [`internal/store/redis/redis.go`](https://github.com/knadh/otpgateway/blob/master/internal/store/redis/redis.go) (Redis OTP store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway"]
  node_server["HTTP server and routes<br/>[main.go]"]
  node_init["Provider initialization<br/>[init.go]"]
end

subgraph group_verification["Verification"]
  node_handlers["OTP API and flow handlers<br/>[handlers.go]"]
  node_models["OTP and provider contracts<br/>[models.go]"]
end

subgraph group_delivery["Delivery providers"]
  node_smtp["SMTP delivery<br/>[smtp.go]"]
  node_pinpoint["Pinpoint SMS<br/>[pinpoint.go]"]
  node_kaleyra["Kaleyra SMS and WhatsApp<br/>[kaleyra.go]"]
  node_webhook["Webhook delivery<br/>[webhook.go]"]
end

subgraph group_state["Challenge state"]
  node_storecontract["Store interface<br/>[store.go]"]
  node_redis[("Redis OTP store<br/>[redis.go]")]
end

subgraph group_web["Web experience"]
  node_webviews["Verification web views"]
  node_modal["JavaScript modal<br/>[otp.js]"]
end

node_client(("Application client"))
node_user(("Verifying user"))
node_redisservice[("Redis service")]
node_mailservice["SMTP service"]
node_aws["AWS Pinpoint"]
node_kaleyraservice["Kaleyra service"]
node_webhooktarget["Webhook endpoint"]

node_client -->|"calls APIs"| node_server
node_server -->|"routes requests"| node_handlers
node_handlers -->|"reads and updates"| node_storecontract
node_handlers -->|"uses OTP data"| node_models
node_handlers -.->|"dispatches delivery"| node_smtp
node_handlers -.->|"dispatches delivery"| node_pinpoint
node_handlers -.->|"dispatches delivery"| node_kaleyra
node_handlers -.->|"dispatches delivery"| node_webhook
node_server -->|"initializes providers"| node_init
node_init -->|"constructs provider"| node_smtp
node_init -->|"constructs provider"| node_pinpoint
node_init -->|"constructs provider"| node_kaleyra
node_init -->|"constructs provider"| node_webhook
node_storecontract -->|"defines OTP operations"| node_models
node_redis -->|"implements"| node_storecontract
node_server -->|"initializes and pings"| node_redis
node_redis -->|"reads and writes"| node_redisservice
node_smtp -->|"sends email"| node_mailservice
node_pinpoint -->|"sends SMS"| node_aws
node_kaleyra -->|"sends messages"| node_kaleyraservice
node_webhook -->|"posts OTP payload"| node_webhooktarget
node_user -->|"uses verification flow"| node_webviews
node_server -->|"serves views and assets"| node_webviews
node_user -->|"opens modal"| node_modal
node_modal -->|"loads OTP view"| node_server
node_modal -->|"returns completion callback"| node_client

click node_server "https://github.com/knadh/otpgateway/blob/master/cmd/otpgateway/main.go"
click node_handlers "https://github.com/knadh/otpgateway/blob/master/cmd/otpgateway/handlers.go"
click node_init "https://github.com/knadh/otpgateway/blob/master/cmd/otpgateway/init.go"
click node_models "https://github.com/knadh/otpgateway/blob/master/pkg/models/models.go"
click node_storecontract "https://github.com/knadh/otpgateway/blob/master/internal/store/store.go"
click node_redis "https://github.com/knadh/otpgateway/blob/master/internal/store/redis/redis.go"
click node_smtp "https://github.com/knadh/otpgateway/blob/master/internal/providers/smtp/smtp.go"
click node_pinpoint "https://github.com/knadh/otpgateway/blob/master/internal/providers/pinpoint/pinpoint.go"
click node_kaleyra "https://github.com/knadh/otpgateway/blob/master/internal/providers/kaleyra/kaleyra.go"
click node_webhook "https://github.com/knadh/otpgateway/blob/master/internal/providers/webhook/webhook.go"
click node_webviews "https://github.com/knadh/otpgateway/tree/master/static"
click node_modal "https://github.com/knadh/otpgateway/blob/master/static/otp.js"

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_server,node_init,node_client,node_user toneBlue
class node_handlers,node_models,node_redisservice toneAmber
class node_smtp,node_pinpoint,node_kaleyra,node_webhook,node_webhooktarget toneMint
class node_storecontract,node_redis toneRose
class node_webviews,node_modal,node_mailservice,node_aws,node_kaleyraservice toneIndigo
```

## Components

### Gateway

- [HTTP server and routes](https://github.com/knadh/otpgateway/blob/master/cmd/otpgateway/main.go): `cmd/otpgateway/main.go`
- [Provider initialization](https://github.com/knadh/otpgateway/blob/master/cmd/otpgateway/init.go): `cmd/otpgateway/init.go`

### Verification

- [OTP API and flow handlers](https://github.com/knadh/otpgateway/blob/master/cmd/otpgateway/handlers.go): `cmd/otpgateway/handlers.go`
- [OTP and provider contracts](https://github.com/knadh/otpgateway/blob/master/pkg/models/models.go): `pkg/models/models.go`

### Delivery providers

- [SMTP delivery](https://github.com/knadh/otpgateway/blob/master/internal/providers/smtp/smtp.go): `internal/providers/smtp/smtp.go`
- [Pinpoint SMS](https://github.com/knadh/otpgateway/blob/master/internal/providers/pinpoint/pinpoint.go): `internal/providers/pinpoint/pinpoint.go`
- [Kaleyra SMS and WhatsApp](https://github.com/knadh/otpgateway/blob/master/internal/providers/kaleyra/kaleyra.go): `internal/providers/kaleyra/kaleyra.go`
- [Webhook delivery](https://github.com/knadh/otpgateway/blob/master/internal/providers/webhook/webhook.go): `internal/providers/webhook/webhook.go`

### Challenge state

- [Store interface](https://github.com/knadh/otpgateway/blob/master/internal/store/store.go): `internal/store/store.go`
- [Redis OTP store](https://github.com/knadh/otpgateway/blob/master/internal/store/redis/redis.go): `internal/store/redis/redis.go`

### Web experience

- [Verification web views](https://github.com/knadh/otpgateway/tree/master/static): `static`
- [JavaScript modal](https://github.com/knadh/otpgateway/blob/master/static/otp.js): `static/otp.js`

### Other components

- **Application client**
- **Verifying user**
- **Redis service**
- **SMTP service**
- **AWS Pinpoint**
- **Kaleyra service**
- **Webhook endpoint**

## Connections

- Application client → HTTP server and routes: calls APIs (evidence: `README.md`)
- HTTP server and routes → OTP API and flow handlers: routes requests (evidence: `cmd/otpgateway/main.go`)
- OTP API and flow handlers → Store interface: reads and updates (evidence: `cmd/otpgateway/handlers.go`)
- OTP API and flow handlers → OTP and provider contracts: uses OTP data (evidence: `cmd/otpgateway/handlers.go`)
- OTP API and flow handlers → SMTP delivery: dispatches delivery
- OTP API and flow handlers → Pinpoint SMS: dispatches delivery
- OTP API and flow handlers → Kaleyra SMS and WhatsApp: dispatches delivery
- OTP API and flow handlers → Webhook delivery: dispatches delivery
- HTTP server and routes → Provider initialization: initializes providers (evidence: `cmd/otpgateway/main.go`)
- Provider initialization → SMTP delivery: constructs provider (evidence: `cmd/otpgateway/init.go`)
- Provider initialization → Pinpoint SMS: constructs provider (evidence: `cmd/otpgateway/init.go`)
- Provider initialization → Kaleyra SMS and WhatsApp: constructs provider (evidence: `cmd/otpgateway/init.go`)
- Provider initialization → Webhook delivery: constructs provider (evidence: `cmd/otpgateway/init.go`)
- Store interface → OTP and provider contracts: defines OTP operations (evidence: `internal/store/store.go`)
- Redis OTP store → Store interface: implements (evidence: `internal/store/redis/redis.go`)
- HTTP server and routes → Redis OTP store: initializes and pings (evidence: `cmd/otpgateway/main.go`)
- Redis OTP store → Redis service: reads and writes (evidence: `internal/store/redis/redis.go`)
- SMTP delivery → SMTP service: sends email (evidence: `internal/providers/smtp/smtp.go`)
- Pinpoint SMS → AWS Pinpoint: sends SMS (evidence: `internal/providers/pinpoint/pinpoint.go`)
- Kaleyra SMS and WhatsApp → Kaleyra service: sends messages (evidence: `internal/providers/kaleyra/kaleyra.go`)
- Webhook delivery → Webhook endpoint: posts OTP payload (evidence: `internal/providers/webhook/webhook.go`)
- Verifying user → Verification web views: uses verification flow (evidence: `README.md`)
- HTTP server and routes → Verification web views: serves views and assets (evidence: `cmd/otpgateway/main.go`)
- Verifying user → JavaScript modal: opens modal (evidence: `static/otp.js`)
- JavaScript modal → HTTP server and routes: loads OTP view (evidence: `static/otp.js`)
- JavaScript modal → Application client: returns completion callback (evidence: `README.md`)
