# oca/connector-telephony architecture

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

- Interactive diagram: https://gitdiagram.com/oca/connector-telephony
- Repository: https://github.com/oca/connector-telephony

## Overview

This repository contains three Odoo addons: phone-number validation and utilities, a VoIP softphone with call/activity/contact handling, and configurable retention for sent SMS. The main user workflow is to find or select a contact, place or receive a SIP call, and record call state in Odoo. The graph preserves the independent phone-number and SMS capabilities. Some subsystem links are based on addon summaries and the file tree; unsampled implementation details are not assumed.

Main entry points: [`voip_oca/static/src/services/voip_oca_service.esm.js`](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/services/voip_oca_service.esm.js) (VoIP State Service), [`voip_oca/static/src/services/voip_agent_service.esm.js`](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/services/voip_agent_service.esm.js) (SIP Call Agent), [`voip_oca/static/src/components/call_list/call_list.esm.js`](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/call_list/call_list.esm.js) (Call And Activity Lists), [`voip_oca/static/src/components/call/call.esm.js`](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/call/call.esm.js) (Call Controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_phone["Phone Utilities"]
  node_phone_ui["Phone Controls"]
  node_phone_common["Phone Utilities<br/>[phone_common.py]"]
  node_phone_validation["Number Validation"]
  node_phone_conversion["Field Conversion"]
  node_phone_wizards["Phone Wizards"]
end

subgraph group_voip_ui["VoIP Interface"]
  node_systray["VoIP Launcher"]
  node_voip_widget["Softphone UI<br/>[softphone.esm.js]"]
  node_voip_lists["Call And Activity Lists<br/>[call_list.esm.js]"]
  node_partner_ui["Contact Panel<br/>[partner.esm.js]"]
  node_call_ui["Call Controls<br/>[call.esm.js]"]
  node_voip_state["VoIP State Service"]
  node_agent["SIP Call Agent"]
end

subgraph group_voip_server["VoIP Records"]
  node_call_model[("Call Records<br/>[voip_call.py]")]
  node_voip_models["VoIP Contact And Activity"]
end

subgraph group_sms["SMS Retention"]
  node_sms_settings["SMS Retention Setting"]
  node_sms_gc["SMS Cleanup<br/>[sms_sms.py]"]
end

node_user(("Odoo User"))
node_phonenumbers["phonenumbers"]
node_sip_library["SIP.js<br/>[sip.js]"]
node_pbx["SIP PBX"]
node_odoo_mail[("Odoo Mail Store")]
node_sms_store[("SMS Records")]

node_user -->|"uses"| node_phone_ui
node_phone_ui -->|"requests dialing"| node_phone_common
node_phone_common -->|"formats numbers"| node_phonenumbers
node_phone_validation -->|"validates numbers"| node_phonenumbers
node_phone_wizards -->|"reformats numbers"| node_phonenumbers
node_user -->|"opens"| node_systray
node_systray -->|"toggles widget"| node_voip_state
node_voip_widget -->|"reads and updates"| node_voip_state
node_voip_lists -->|"searches records"| node_voip_state
node_partner_ui -->|"updates call context"| node_voip_state
node_call_ui -->|"controls calls"| node_agent
node_call_ui -->|"reads call state"| node_voip_state
node_agent -->|"updates call state"| node_voip_state
node_agent -->|"creates SIP sessions"| node_sip_library
node_agent -->|"registers and calls"| node_pbx
node_agent -->|"creates and updates calls"| node_call_model
node_voip_state -->|"requests contacts and activities"| node_voip_models
node_voip_state -->|"requests recent calls"| node_call_model
node_voip_state -->|"inserts records"| node_odoo_mail
node_voip_lists -->|"reads records"| node_odoo_mail
node_user -->|"configures retention"| node_sms_settings
node_sms_settings -->|"sets purge interval"| node_sms_gc
node_sms_gc -->|"deletes expired marked SMS"| node_sms_store

click node_phone_ui "https://github.com/oca/connector-telephony/tree/18.0/base_phone/static/src/components"
click node_phone_common "https://github.com/oca/connector-telephony/blob/18.0/base_phone/models/phone_common.py"
click node_phone_validation "https://github.com/oca/connector-telephony/blob/18.0/base_phone/models/phone_validation_mixin.py"
click node_phone_conversion "https://github.com/oca/connector-telephony/blob/18.0/base_phone/models/ir_fields_converter.py"
click node_phone_wizards "https://github.com/oca/connector-telephony/tree/18.0/base_phone/wizard"
click node_systray "https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/voip_oca_systray/voip_oca_systray.esm.js"
click node_voip_widget "https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/softphone/softphone.esm.js"
click node_voip_lists "https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/call_list/call_list.esm.js"
click node_partner_ui "https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/partner/partner.esm.js"
click node_call_ui "https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/call/call.esm.js"
click node_voip_state "https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/services/voip_oca_service.esm.js"
click node_agent "https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/services/voip_agent_service.esm.js"
click node_sip_library "https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/lib/sip.js"
click node_call_model "https://github.com/oca/connector-telephony/blob/18.0/voip_oca/models/voip_call.py"
click node_voip_models "https://github.com/oca/connector-telephony/tree/18.0/voip_oca/models"
click node_sms_settings "https://github.com/oca/connector-telephony/blob/18.0/sms_no_automatic_delete/models/res_config_settings.py"
click node_sms_gc "https://github.com/oca/connector-telephony/blob/18.0/sms_no_automatic_delete/models/sms_sms.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_phone_ui,node_phone_common,node_phone_validation,node_phone_conversion,node_phone_wizards,node_user toneBlue
class node_systray,node_voip_widget,node_voip_lists,node_partner_ui,node_call_ui,node_voip_state,node_agent,node_odoo_mail,node_sms_store toneAmber
class node_call_model,node_voip_models toneMint
class node_sms_settings,node_sms_gc toneRose
class node_phonenumbers,node_pbx toneIndigo
class node_sip_library toneTeal
```

## Components

### Phone Utilities

- [Phone Controls](https://github.com/oca/connector-telephony/tree/18.0/base_phone/static/src/components): `base_phone/static/src/components`
- [Phone Utilities](https://github.com/oca/connector-telephony/blob/18.0/base_phone/models/phone_common.py): `base_phone/models/phone_common.py`
- [Number Validation](https://github.com/oca/connector-telephony/blob/18.0/base_phone/models/phone_validation_mixin.py): `base_phone/models/phone_validation_mixin.py`
- [Field Conversion](https://github.com/oca/connector-telephony/blob/18.0/base_phone/models/ir_fields_converter.py): `base_phone/models/ir_fields_converter.py`
- [Phone Wizards](https://github.com/oca/connector-telephony/tree/18.0/base_phone/wizard): `base_phone/wizard`

### VoIP Interface

- [VoIP Launcher](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/voip_oca_systray/voip_oca_systray.esm.js): `voip_oca/static/src/components/voip_oca_systray/voip_oca_systray.esm.js`
- [Softphone UI](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/softphone/softphone.esm.js): `voip_oca/static/src/components/softphone/softphone.esm.js`
- [Call And Activity Lists](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/call_list/call_list.esm.js): `voip_oca/static/src/components/call_list/call_list.esm.js`
- [Contact Panel](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/partner/partner.esm.js): `voip_oca/static/src/components/partner/partner.esm.js`
- [Call Controls](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/components/call/call.esm.js): `voip_oca/static/src/components/call/call.esm.js`
- [VoIP State Service](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/services/voip_oca_service.esm.js): `voip_oca/static/src/services/voip_oca_service.esm.js`
- [SIP Call Agent](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/src/services/voip_agent_service.esm.js): `voip_oca/static/src/services/voip_agent_service.esm.js`

### VoIP Records

- [Call Records](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/models/voip_call.py): `voip_oca/models/voip_call.py`
- [VoIP Contact And Activity](https://github.com/oca/connector-telephony/tree/18.0/voip_oca/models): `voip_oca/models`

### SMS Retention

- [SMS Retention Setting](https://github.com/oca/connector-telephony/blob/18.0/sms_no_automatic_delete/models/res_config_settings.py): `sms_no_automatic_delete/models/res_config_settings.py`
- [SMS Cleanup](https://github.com/oca/connector-telephony/blob/18.0/sms_no_automatic_delete/models/sms_sms.py): `sms_no_automatic_delete/models/sms_sms.py`

### Other components

- **Odoo User**
- **phonenumbers**
- [SIP.js](https://github.com/oca/connector-telephony/blob/18.0/voip_oca/static/lib/sip.js): `voip_oca/static/lib/sip.js`
- **SIP PBX**
- **Odoo Mail Store**
- **SMS Records**

## Connections

- Odoo User → Phone Controls: uses
- Phone Controls → Phone Utilities: requests dialing
- Phone Utilities → phonenumbers: formats numbers
- Number Validation → phonenumbers: validates numbers
- Phone Wizards → phonenumbers: reformats numbers
- Odoo User → VoIP Launcher: opens
- VoIP Launcher → VoIP State Service: toggles widget
- Softphone UI → VoIP State Service: reads and updates
- Call And Activity Lists → VoIP State Service: searches records
- Contact Panel → VoIP State Service: updates call context
- Call Controls → SIP Call Agent: controls calls
- Call Controls → VoIP State Service: reads call state
- SIP Call Agent → VoIP State Service: updates call state
- SIP Call Agent → SIP.js: creates SIP sessions
- SIP Call Agent → SIP PBX: registers and calls
- SIP Call Agent → Call Records: creates and updates calls
- VoIP State Service → VoIP Contact And Activity: requests contacts and activities
- VoIP State Service → Call Records: requests recent calls
- VoIP State Service → Odoo Mail Store: inserts records
- Call And Activity Lists → Odoo Mail Store: reads records
- Odoo User → SMS Retention Setting: configures retention
- SMS Retention Setting → SMS Cleanup: sets purge interval
- SMS Cleanup → SMS Records: deletes expired marked SMS