# syedyaseenjamal/voxa-backend architecture

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

- Interactive diagram: https://gitdiagram.com/syedyaseenjamal/voxa-backend
- Repository: https://github.com/syedyaseenjamal/voxa-backend

## Overview

Voxa Backend is a multi-tenant communications and campaign API for administrators and company users. The main user journey is to authenticate, manage tenant and user access, maintain leads and integrations, then operate campaigns and telephony/AI call workflows. The map includes billing and DID management as separate product areas. README content was absent, and most implementation excerpts were partial, so uncertain internal and persistence links are omitted.

Main entry points: [`src/app.js`](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/app.js) (Express application), [`src/modules/telephony/telephony.controller.js`](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/telephony/telephony.controller.js) (Telephony workflows), [`src/modules/auth/auth.routes.js`](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/auth/auth.routes.js) (Authentication), [`src/modules/leads/leads.controller.js`](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/leads/leads.controller.js) (Lead management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and access"]
  node_app["Express application<br/>[app.js]"]
  node_auth["Authentication<br/>[auth.routes.js]"]
  node_authctrl["Auth handlers<br/>[auth.controller.js]"]
  node_access["Access middleware<br/>[authenticate.js]"]
end

subgraph group_tenants["Tenant administration"]
  node_companies["Company management<br/>[company.routes.js]"]
  node_companyusers["Company users"]
  node_roles["Roles and permissions<br/>[role.routes.js]"]
  node_adminusers["Admin users"]
end

subgraph group_campaigns["Leads and campaigns"]
  node_leads["Lead management"]
  node_integrations["Platform integrations"]
  node_leadmodels["Lead data<br/>[lead.model.js]"]
  node_campaignsmeta["Meta campaigns"]
  node_ivrcampaigns["IVR campaigns"]
  node_obd["OBD CMS service<br/>[obdCms.service.js]"]
end

subgraph group_communications["Voice and AI"]
  node_dids["DID management<br/>[did.controller.js]"]
  node_dialer["Dialer control"]
  node_telephony["Telephony workflows"]
  node_telephonyservice["Call processing"]
  node_aiagents["AI agent workflows"]
end

subgraph group_platform["Billing and integrations"]
  node_orders["Orders<br/>[order.routes.js]"]
  node_billing["Billing plans<br/>[billing.routes.js]"]
end

node_client(("API client"))
node_mongo[("MongoDB<br/>[db.js]")]
node_meta["Meta Graph API"]
node_obdcms["OBD CMS"]
node_asterisk["Asterisk interfaces"]
node_aipipeline["AI pipeline"]

node_client -->|"sends requests"| node_app
node_app -->|"routes requests"| node_auth
node_auth -->|"dispatches"| node_authctrl
node_app -->|"applies access checks"| node_access
node_app -->|"routes requests"| node_companies
node_app -->|"routes requests"| node_companyusers
node_app -->|"routes requests"| node_roles
node_app -->|"routes requests"| node_adminusers
node_app -->|"routes requests"| node_leads
node_app -->|"routes requests"| node_integrations
node_app -->|"routes requests"| node_campaignsmeta
node_app -->|"routes requests"| node_ivrcampaigns
node_app -->|"routes requests"| node_dids
node_app -->|"routes requests"| node_dialer
node_app -->|"routes requests"| node_telephony
node_app -->|"routes requests"| node_aiagents
node_app -->|"routes requests"| node_orders
node_app -->|"routes requests"| node_billing
node_leads -->|"reads and writes"| node_leadmodels
node_campaignsmeta -->|"requests campaign data"| node_meta
node_ivrcampaigns -->|"calls campaign operations"| node_obd
node_obd -->|"manages campaigns"| node_obdcms
node_telephony -->|"calls processing"| node_telephonyservice
node_telephony -->|"fetches call logs"| node_asterisk
node_telephony -->|"submits call workflows"| node_aipipeline
node_aiagents -->|"proxies pipeline calls"| node_aipipeline
node_dialer -->|"controls calls"| node_asterisk

click node_app "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/app.js"
click node_auth "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/auth/auth.routes.js"
click node_authctrl "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/auth/auth.controller.js"
click node_access "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/middlewares/authenticate.js"
click node_companies "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/companies/company.routes.js"
click node_companyusers "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/company-users/companyUser.routes.js"
click node_roles "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/roles/role.routes.js"
click node_adminusers "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/admin-users/adminUser.routes.js"
click node_leads "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/leads/leads.controller.js"
click node_integrations "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/integrations/integration.routes.js"
click node_leadmodels "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/integrations/lead.model.js"
click node_campaignsmeta "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/integrations/campaigns.controller.js"
click node_ivrcampaigns "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/ivr-campaigns/ivrCampaign.controller.js"
click node_obd "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/ivr-campaigns/obdCms.service.js"
click node_dids "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/dids/did.controller.js"
click node_dialer "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/dialer/dialer.controller.js"
click node_telephony "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/telephony/telephony.controller.js"
click node_telephonyservice "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/telephony/telephony.service.js"
click node_aiagents "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/ai-agents/aiAgent.controller.js"
click node_orders "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/orders/order.routes.js"
click node_billing "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/billing/billing.routes.js"
click node_mongo "https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/config/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_app,node_auth,node_authctrl,node_access,node_client toneBlue
class node_companies,node_companyusers,node_roles,node_adminusers,node_mongo toneAmber
class node_leads,node_integrations,node_leadmodels,node_campaignsmeta,node_ivrcampaigns,node_obd,node_meta toneMint
class node_dids,node_dialer,node_telephony,node_telephonyservice,node_aiagents toneRose
class node_orders,node_billing,node_obdcms,node_asterisk,node_aipipeline toneIndigo
```

## Components

### API and access

- [Express application](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/app.js): `src/app.js`
- [Authentication](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/auth/auth.routes.js): `src/modules/auth/auth.routes.js`
- [Auth handlers](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/auth/auth.controller.js): `src/modules/auth/auth.controller.js`
- [Access middleware](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/middlewares/authenticate.js): `src/middlewares/authenticate.js`

### Tenant administration

- [Company management](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/companies/company.routes.js): `src/modules/companies/company.routes.js`
- [Company users](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/company-users/companyUser.routes.js): `src/modules/company-users/companyUser.routes.js`
- [Roles and permissions](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/roles/role.routes.js): `src/modules/roles/role.routes.js`
- [Admin users](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/admin-users/adminUser.routes.js): `src/modules/admin-users/adminUser.routes.js`

### Leads and campaigns

- [Lead management](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/leads/leads.controller.js): `src/modules/leads/leads.controller.js`
- [Platform integrations](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/integrations/integration.routes.js): `src/modules/integrations/integration.routes.js`
- [Lead data](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/integrations/lead.model.js): `src/modules/integrations/lead.model.js`
- [Meta campaigns](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/integrations/campaigns.controller.js): `src/modules/integrations/campaigns.controller.js`
- [IVR campaigns](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/ivr-campaigns/ivrCampaign.controller.js): `src/modules/ivr-campaigns/ivrCampaign.controller.js`
- [OBD CMS service](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/ivr-campaigns/obdCms.service.js): `src/modules/ivr-campaigns/obdCms.service.js`

### Voice and AI

- [DID management](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/dids/did.controller.js): `src/modules/dids/did.controller.js`
- [Dialer control](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/dialer/dialer.controller.js): `src/modules/dialer/dialer.controller.js`
- [Telephony workflows](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/telephony/telephony.controller.js): `src/modules/telephony/telephony.controller.js`
- [Call processing](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/telephony/telephony.service.js): `src/modules/telephony/telephony.service.js`
- [AI agent workflows](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/ai-agents/aiAgent.controller.js): `src/modules/ai-agents/aiAgent.controller.js`

### Billing and integrations

- [Orders](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/orders/order.routes.js): `src/modules/orders/order.routes.js`
- [Billing plans](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/modules/billing/billing.routes.js): `src/modules/billing/billing.routes.js`

### Other components

- **API client**
- [MongoDB](https://github.com/syedyaseenjamal/voxa-backend/blob/main/src/config/db.js): `src/config/db.js`
- **Meta Graph API**
- **OBD CMS**
- **Asterisk interfaces**
- **AI pipeline**

## Connections

- API client → Express application: sends requests
- Express application → Authentication: routes requests
- Authentication → Auth handlers: dispatches
- Express application → Access middleware: applies access checks
- Express application → Company management: routes requests
- Express application → Company users: routes requests
- Express application → Roles and permissions: routes requests
- Express application → Admin users: routes requests
- Express application → Lead management: routes requests
- Express application → Platform integrations: routes requests
- Express application → Meta campaigns: routes requests
- Express application → IVR campaigns: routes requests
- Express application → DID management: routes requests
- Express application → Dialer control: routes requests
- Express application → Telephony workflows: routes requests
- Express application → AI agent workflows: routes requests
- Express application → Orders: routes requests
- Express application → Billing plans: routes requests
- Lead management → Lead data: reads and writes
- Meta campaigns → Meta Graph API: requests campaign data
- IVR campaigns → OBD CMS service: calls campaign operations
- OBD CMS service → OBD CMS: manages campaigns
- Telephony workflows → Call processing: calls processing
- Telephony workflows → Asterisk interfaces: fetches call logs
- Telephony workflows → AI pipeline: submits call workflows
- AI agent workflows → AI pipeline: proxies pipeline calls
- Dialer control → Asterisk interfaces: controls calls