# sujalsubedixx/nest_sms architecture

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

- Interactive diagram: https://gitdiagram.com/sujalsubedixx/nest_sms
- Repository: https://github.com/sujalsubedixx/nest_sms

## Overview

Mini SMS Gateway is a JWT-protected REST API for user accounts, wallet-backed SMS delivery, message history, and provider health. Its main workflow validates and normalizes recipients, calculates SMS parts and cost, atomically charges credits and stores pending messages, then attempts providers in priority order; unsuccessful delivery triggers a guarded refund. Separate branches handle registration/login, filtered logs, and route-health reporting. The sampled source shows the send orchestration and persistence responsibilities; other documented capabilities are represented where the README or source index supports them.

Main entry points: [`controllers/sms.controller.js`](https://github.com/sujalsubedixx/nest_sms/blob/main/controllers/sms.controller.js) (SMS handlers), [`routes/sms.route.js`](https://github.com/sujalsubedixx/nest_sms/blob/main/routes/sms.route.js) (SMS routes), [`index.js`](https://github.com/sujalsubedixx/nest_sms/blob/main/index.js) (API server), [`services/deliver.js`](https://github.com/sujalsubedixx/nest_sms/blob/main/services/deliver.js) (Failover delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_user_routes["Account routes<br/>[user.route.js]"]
  node_user_controller["Account handlers<br/>[user.controller.js]"]
  node_auth["JWT authentication<br/>[auth.js]"]
  node_sms_routes["SMS routes<br/>[sms.route.js]"]
  node_rate_limiter["Send rate limit<br/>[rateLimiter.js]"]
  node_server["API server<br/>[index.js]"]
end

subgraph group_delivery["SMS delivery"]
  node_sms_controller["SMS handlers<br/>[sms.controller.js]"]
  node_delivery_service["Failover delivery<br/>[deliver.js]"]
  node_refund_service["Refund logic<br/>[refund.js]"]
end

subgraph group_providers["Provider routing"]
  node_provider_registry["Provider lookup<br/>[index.js]"]
  node_mock_provider["Mock provider<br/>[mockProvider.js]"]
end

subgraph group_state["Persistent state"]
  node_user_model[("User records<br/>[user.model.js]")]
  node_wallet_model[("Wallet credits<br/>[wallet.model.js]")]
  node_message_model[("Message records<br/>[message.model.js]")]
  node_provider_model[("Provider records<br/>[provider.model.js]")]
end

subgraph group_utilities["Shared utilities"]
  node_number_normalizer["Number normalization<br/>[normalizeNumber.js]"]
  node_part_counter["SMS part counter<br/>[smsPart.js]"]
  node_database_connection["Database connection<br/>[db.js]"]
end

node_client(("API client"))

node_client -->|"registers or logs in"| node_user_routes
node_user_routes -->|"routes requests"| node_user_controller
node_user_controller -->|"creates or looks up"| node_user_model
node_user_controller -->|"creates wallet"| node_wallet_model
node_client -->|"sends SMS or queries"| node_sms_routes
node_sms_routes -->|"checks token"| node_auth
node_sms_routes -->|"limits sends"| node_rate_limiter
node_sms_routes -->|"routes requests"| node_sms_controller
node_sms_controller -->|"normalizes recipients"| node_number_normalizer
node_sms_controller -->|"counts parts"| node_part_counter
node_sms_controller -->|"deducts credits"| node_wallet_model
node_sms_controller -->|"creates and queries"| node_message_model
node_sms_controller -->|"loads providers"| node_provider_registry
node_sms_controller -->|"dispatches messages"| node_delivery_service
node_sms_controller -->|"refunds delivery errors"| node_refund_service
node_sms_controller -->|"reads route health"| node_provider_model
node_delivery_service -->|"tries providers"| node_mock_provider
node_delivery_service -->|"records attempts"| node_message_model
node_delivery_service -->|"refunds exhaustion"| node_refund_service
node_provider_registry -->|"loads priorities"| node_provider_model
node_provider_registry -->|"builds providers"| node_mock_provider
node_mock_provider -->|"uses provider data"| node_provider_model
node_refund_service -->|"marks failed once"| node_message_model
node_refund_service -->|"restores credits"| node_wallet_model
node_server -->|"mounts routes"| node_user_routes
node_server -->|"mounts routes"| node_sms_routes
node_server -->|"connects database"| node_database_connection
node_server -->|"seeds defaults"| node_provider_model

click node_user_routes "https://github.com/sujalsubedixx/nest_sms/blob/main/routes/user.route.js"
click node_user_controller "https://github.com/sujalsubedixx/nest_sms/blob/main/controllers/user.controller.js"
click node_auth "https://github.com/sujalsubedixx/nest_sms/blob/main/middleware/auth.js"
click node_sms_routes "https://github.com/sujalsubedixx/nest_sms/blob/main/routes/sms.route.js"
click node_rate_limiter "https://github.com/sujalsubedixx/nest_sms/blob/main/middleware/rateLimiter.js"
click node_sms_controller "https://github.com/sujalsubedixx/nest_sms/blob/main/controllers/sms.controller.js"
click node_number_normalizer "https://github.com/sujalsubedixx/nest_sms/blob/main/utils/normalizeNumber.js"
click node_part_counter "https://github.com/sujalsubedixx/nest_sms/blob/main/utils/smsPart.js"
click node_delivery_service "https://github.com/sujalsubedixx/nest_sms/blob/main/services/deliver.js"
click node_refund_service "https://github.com/sujalsubedixx/nest_sms/blob/main/services/refund.js"
click node_provider_registry "https://github.com/sujalsubedixx/nest_sms/blob/main/providers/index.js"
click node_mock_provider "https://github.com/sujalsubedixx/nest_sms/blob/main/providers/mockProvider.js"
click node_user_model "https://github.com/sujalsubedixx/nest_sms/blob/main/models/user.model.js"
click node_wallet_model "https://github.com/sujalsubedixx/nest_sms/blob/main/models/wallet.model.js"
click node_message_model "https://github.com/sujalsubedixx/nest_sms/blob/main/models/message.model.js"
click node_provider_model "https://github.com/sujalsubedixx/nest_sms/blob/main/models/provider.model.js"
click node_server "https://github.com/sujalsubedixx/nest_sms/blob/main/index.js"
click node_database_connection "https://github.com/sujalsubedixx/nest_sms/blob/main/utils/db.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_user_routes,node_user_controller,node_auth,node_sms_routes,node_rate_limiter,node_server,node_client toneBlue
class node_sms_controller,node_delivery_service,node_refund_service toneAmber
class node_provider_registry,node_mock_provider toneMint
class node_user_model,node_wallet_model,node_message_model,node_provider_model toneRose
class node_number_normalizer,node_part_counter,node_database_connection toneIndigo
```

## Components

### API and access

- [Account routes](https://github.com/sujalsubedixx/nest_sms/blob/main/routes/user.route.js): `routes/user.route.js`
- [Account handlers](https://github.com/sujalsubedixx/nest_sms/blob/main/controllers/user.controller.js): `controllers/user.controller.js`
- [JWT authentication](https://github.com/sujalsubedixx/nest_sms/blob/main/middleware/auth.js): `middleware/auth.js`
- [SMS routes](https://github.com/sujalsubedixx/nest_sms/blob/main/routes/sms.route.js): `routes/sms.route.js`
- [Send rate limit](https://github.com/sujalsubedixx/nest_sms/blob/main/middleware/rateLimiter.js): `middleware/rateLimiter.js`
- [API server](https://github.com/sujalsubedixx/nest_sms/blob/main/index.js): `index.js`

### SMS delivery

- [SMS handlers](https://github.com/sujalsubedixx/nest_sms/blob/main/controllers/sms.controller.js): `controllers/sms.controller.js`
- [Failover delivery](https://github.com/sujalsubedixx/nest_sms/blob/main/services/deliver.js): `services/deliver.js`
- [Refund logic](https://github.com/sujalsubedixx/nest_sms/blob/main/services/refund.js): `services/refund.js`

### Provider routing

- [Provider lookup](https://github.com/sujalsubedixx/nest_sms/blob/main/providers/index.js): `providers/index.js`
- [Mock provider](https://github.com/sujalsubedixx/nest_sms/blob/main/providers/mockProvider.js): `providers/mockProvider.js`

### Persistent state

- [User records](https://github.com/sujalsubedixx/nest_sms/blob/main/models/user.model.js): `models/user.model.js`
- [Wallet credits](https://github.com/sujalsubedixx/nest_sms/blob/main/models/wallet.model.js): `models/wallet.model.js`
- [Message records](https://github.com/sujalsubedixx/nest_sms/blob/main/models/message.model.js): `models/message.model.js`
- [Provider records](https://github.com/sujalsubedixx/nest_sms/blob/main/models/provider.model.js): `models/provider.model.js`

### Shared utilities

- [Number normalization](https://github.com/sujalsubedixx/nest_sms/blob/main/utils/normalizeNumber.js): `utils/normalizeNumber.js`
- [SMS part counter](https://github.com/sujalsubedixx/nest_sms/blob/main/utils/smsPart.js): `utils/smsPart.js`
- [Database connection](https://github.com/sujalsubedixx/nest_sms/blob/main/utils/db.js): `utils/db.js`

### Other components

- **API client**

## Connections

- API client → Account routes: registers or logs in (evidence: `README.md`)
- Account routes → Account handlers: routes requests (evidence: `routes/user.route.js`)
- Account handlers → User records: creates or looks up (evidence: `controllers/user.controller.js`)
- Account handlers → Wallet credits: creates wallet (evidence: `controllers/user.controller.js`)
- API client → SMS routes: sends SMS or queries (evidence: `README.md`)
- SMS routes → JWT authentication: checks token (evidence: `routes/sms.route.js`)
- SMS routes → Send rate limit: limits sends (evidence: `routes/sms.route.js`)
- SMS routes → SMS handlers: routes requests (evidence: `routes/sms.route.js`)
- SMS handlers → Number normalization: normalizes recipients (evidence: `controllers/sms.controller.js`)
- SMS handlers → SMS part counter: counts parts (evidence: `controllers/sms.controller.js`)
- SMS handlers → Wallet credits: deducts credits (evidence: `controllers/sms.controller.js`)
- SMS handlers → Message records: creates and queries (evidence: `controllers/sms.controller.js`)
- SMS handlers → Provider lookup: loads providers (evidence: `controllers/sms.controller.js`)
- SMS handlers → Failover delivery: dispatches messages (evidence: `controllers/sms.controller.js`)
- SMS handlers → Refund logic: refunds delivery errors (evidence: `controllers/sms.controller.js`)
- SMS handlers → Provider records: reads route health (evidence: `controllers/sms.controller.js`)
- Failover delivery → Mock provider: tries providers (evidence: `services/deliver.js`)
- Failover delivery → Message records: records attempts (evidence: `services/deliver.js`)
- Failover delivery → Refund logic: refunds exhaustion (evidence: `services/deliver.js`)
- Provider lookup → Provider records: loads priorities (evidence: `providers/index.js`)
- Provider lookup → Mock provider: builds providers (evidence: `providers/index.js`)
- Mock provider → Provider records: uses provider data (evidence: `providers/mockProvider.js`)
- Refund logic → Message records: marks failed once (evidence: `services/refund.js`)
- Refund logic → Wallet credits: restores credits (evidence: `services/refund.js`)
- API server → Account routes: mounts routes (evidence: `index.js`)
- API server → SMS routes: mounts routes (evidence: `index.js`)
- API server → Database connection: connects database (evidence: `index.js`)
- API server → Provider records: seeds defaults (evidence: `index.js`)