# signalwire/freeswitch architecture

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

- Interactive diagram: https://gitdiagram.com/signalwire/freeswitch
- Repository: https://github.com/signalwire/freeswitch

## Overview

1. FreeSWITCH is a telecom application server with a central C/C++ core in `src/` and a large plugin surface in `src/mod/`. The core owns session lifecycle, channel state, media handling, event dispatch, scheduling, logging, XML config parsing, and module loading.

2. The main runtime boundary is between the core and loadable modules. Core code lives in files like `switch_core.c`, `switch_channel.c`, `switch_rtp.c`, `switch_ivr*.c`, `switch_event.c`, and `switch_loadable_module.c`; modules are compiled independently and loaded at runtime as shared objects/DLLs.

3. Configuration is XML-driven and organized by deployment profile under `conf/` (`vanilla`, `minimal`, `testing`, `sbc`, `softphone`, etc.). The key config files define autoloaded modules, SIP profiles, directories/users, dialplans, language prompts, variables, and feature-specific routing.

4. The signaling ingress/egress layer is primarily in endpoint modules under `src/mod/endpoints/`. The dominant SIP stack is `mod_sofia`, but the repo also includes other endpoint integrations such as `mod_skinny`, `mod_verto`, `mod_rtmp`, `mod_h323`, `mod_opal`, `mod_loopback`, and `mod_alsa`. These modules create/accept calls and hand them to the core session engine.

5. Media processing is split across core media code and specialized modules. The core handles RTP/session media control; codec and format support is provided by modules under `src/mod/codecs/` and `src/mod/formats/`, while audio/video utilities are backed by vendored libraries like `libvpx`, `libyuv`, `libsrtp`, `spandsp`, `libsndfile`, `opus`, `sofia-sip`, and others in `libs/`.

6. Call behavior is implemented through application modules in `src/mod/applications/` and related core IVR helpers. This includes conferencing, voicemail, callcenter, FIFO, limit/rate control, directory lookup, dialing tools, recording, fax/modem support, HTTP API-driven apps, and routing helpers like LCR/distributor/easyroute.

7. Scriptable call control is a major subsystem. Language bindings under `src/mod/languages/` and `src/mod/asr_tts/` expose the core to Lua, Python 3, Perl, Java, managed/.NET, V8/JavaScript, basic scripting, and TTS/ASR engines. These modules typically embed an interpreter or bind into the core via SWIG-generated wrappers.

8. External integration is centered on the event bus and API surfaces. `mod_event_socket`, `mod_event_multicast`, `mod_amqp`, `mod_erlang_event`, `mod_snmp`, and the CDR modules publish or consume call events. XML and HTTP-facing integration is provided by `mod_xml_curl`, `mod_xml_rpc`, `mod_xml_scgi`, `mod_httapi`, and `mod_signalwire` for SignalWire cloud connectivity.

9. Data persistence and lookup are isolated into database and cache modules. `src/mod/databases/` and `src/mod/event_handlers/` include PostgreSQL, MariaDB, ODBC, SQLite, Redis, Memcache, Mongo, and Hiredis integrations. These are used for CDR storage, directory/dialplan lookup, billing, routing, and cached state.

10. The repository also contains the client/tooling ecosystem around the core. `libs/esl/` is the Event Socket Library with bindings for Java, Lua, Perl, PHP, Python3, Ruby, C#, and Tcl; `fs_cli`, `fscomm`, and the web portal in `htdocs/portal/` are example clients and UIs that talk to the server rather than being part of the telephony core itself.

11. Build and packaging are first-class concerns. The repo supports autotools, CMake, and platform-specific project files for Visual Studio and Windows installers. There are extensive Docker definitions under `docker/` and `.github/docker/`, plus Debian/RPM packaging under `debian/`, `scripts/packaging/`, and `yum/`.

12. Test coverage is organized by subsystem. `tests/unit/` exercises core call control, SIP/RTP, XML, codecs, VAD, and media behaviors, while individual modules often carry their own test directories and sample configs. CI is driven by GitHub Actions workflows for Linux, macOS, Windows, Docker-in-Docker, and static analysis.

13. In architecture-diagram terms, the main flow is: signaling enters through endpoint modules, the core creates/controls sessions, media flows through codec/format and RTP processing, dialplan/app modules implement call logic, and events/CDRs/API calls flow outward to sockets, databases, message buses, HTTP/XML services, and external cloud services like SignalWire.

14. The `libs/` tree is mostly vendored dependencies and companion libraries rather than business logic. It matters architecturally because many features are optional at build time and are wired in through module/link-time boundaries instead of being implemented inside the core daemon.

Main entry points: [`src/switch_loadable_module.c`](https://github.com/signalwire/freeswitch/blob/master/src/switch_loadable_module.c) (Module loader), [`src/switch_core.c`](https://github.com/signalwire/freeswitch/blob/master/src/switch_core.c) (Core runtime), [`src/mod/endpoints/mod_sofia/mod_sofia.c`](https://github.com/signalwire/freeswitch/blob/master/src/mod/endpoints/mod_sofia/mod_sofia.c) (mod_sofia), [`src/switch_core_media.c`](https://github.com/signalwire/freeswitch/blob/master/src/switch_core_media.c) (Media engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core"]
  node_repo["FreeSWITCH<br/>telecom platform"]
  node_core_runtime["Core runtime<br/>daemon core<br/>[switch_core.c]"]
  node_session_channel["Sessions & channels<br/>call control"]
  node_media_rtp["Media engine<br/>media control"]
  node_ivr_flow["IVR flow<br/>call flow<br/>[switch_ivr.c]"]
  node_events["Event bus<br/>event system<br/>[switch_event.c]"]
  node_xml_config["XML config<br/>config parser"]
  node_module_loader["Module loader<br/>plugin loader"]
end

subgraph group_modules["Modules"]
  node_sofia["mod_sofia<br/>SIP endpoint<br/>[mod_sofia.c]"]
  node_other_endpoints["Other endpoints<br/>endpoint plugins<br/>[mod_skinny.c]"]
  node_codec_modules["Codecs<br/>codec plugins<br/>[mod_opus.c]"]
  node_format_modules["Formats<br/>file/media plugins<br/>[mod_sndfile.c]"]
  node_app_modules["Applications<br/>call apps<br/>[mod_conference.c]"]
  node_script_bindings["Script bindings<br/>language modules<br/>[mod_lua.cpp]"]
  node_event_integration["Event/API I/O<br/>integration modules<br/>[mod_event_socket.c]"]
  node_cdr_storage["Data store<br/>db/cache modules<br/>[mod_pgsql.c]"]
end

subgraph group_support["Support"]
  node_sip_and_xml_profiles["Deployment profiles<br/>xml configs<br/>[freeswitch.xml]"]
  node_esl_clients["ESL clients<br/>client library<br/>[esl.c]"]
  node_build_packaging["Build & packaging<br/>tooling<br/>[configure.ac]"]
  node_tests["Tests<br/>test suite<br/>[Makefile.am]"]
  node_vendor_libs["Vendored libs<br/>third-party libs<br/>[CMakeLists.txt]"]
end

node_repo -->|"contains"| node_core_runtime
node_repo -->|"loads"| node_module_loader
node_core_runtime -->|"orchestrates"| node_session_channel
node_core_runtime -->|"controls"| node_media_rtp
node_core_runtime -->|"invokes"| node_ivr_flow
node_core_runtime -->|"emits"| node_events
node_core_runtime -->|"reads"| node_xml_config
node_module_loader -->|"loads"| node_sofia
node_module_loader -->|"loads"| node_other_endpoints
node_module_loader -->|"loads"| node_codec_modules
node_module_loader -->|"loads"| node_format_modules
node_module_loader -->|"loads"| node_app_modules
node_module_loader -->|"loads"| node_script_bindings
node_module_loader -->|"loads"| node_event_integration
node_module_loader -->|"loads"| node_cdr_storage
node_sofia -->|"creates"| node_session_channel
node_other_endpoints -->|"creates"| node_session_channel
node_codec_modules -->|"extends"| node_media_rtp
node_format_modules -->|"feeds"| node_media_rtp
node_app_modules -->|"implements"| node_ivr_flow
node_script_bindings -->|"consumes"| node_events
node_event_integration -->|"bridges"| node_events
node_cdr_storage -->|"persists"| node_events
node_sip_and_xml_profiles -->|"configures"| node_sofia
node_sip_and_xml_profiles -->|"routes"| node_app_modules
node_esl_clients -->|"connects"| node_event_integration
node_build_packaging -->|"produces"| node_module_loader
node_build_packaging -->|"vendors"| node_vendor_libs
node_tests -->|"verifies"| node_core_runtime
node_tests -->|"verifies"| node_sofia
node_tests -->|"verifies"| node_media_rtp

click node_core_runtime "https://github.com/signalwire/freeswitch/blob/master/src/switch_core.c"
click node_session_channel "https://github.com/signalwire/freeswitch/blob/master/src/switch_core_session.c"
click node_media_rtp "https://github.com/signalwire/freeswitch/blob/master/src/switch_core_media.c"
click node_ivr_flow "https://github.com/signalwire/freeswitch/blob/master/src/switch_ivr.c"
click node_events "https://github.com/signalwire/freeswitch/blob/master/src/switch_event.c"
click node_xml_config "https://github.com/signalwire/freeswitch/blob/master/src/switch_xml_config.c"
click node_module_loader "https://github.com/signalwire/freeswitch/blob/master/src/switch_loadable_module.c"
click node_sofia "https://github.com/signalwire/freeswitch/blob/master/src/mod/endpoints/mod_sofia/mod_sofia.c"
click node_other_endpoints "https://github.com/signalwire/freeswitch/blob/master/src/mod/endpoints/mod_skinny/mod_skinny.c"
click node_codec_modules "https://github.com/signalwire/freeswitch/blob/master/src/mod/codecs/mod_opus/mod_opus.c"
click node_format_modules "https://github.com/signalwire/freeswitch/blob/master/src/mod/formats/mod_sndfile/mod_sndfile.c"
click node_app_modules "https://github.com/signalwire/freeswitch/blob/master/src/mod/applications/mod_conference/mod_conference.c"
click node_script_bindings "https://github.com/signalwire/freeswitch/blob/master/src/mod/languages/mod_lua/mod_lua.cpp"
click node_event_integration "https://github.com/signalwire/freeswitch/blob/master/src/mod/event_handlers/mod_event_socket/mod_event_socket.c"
click node_cdr_storage "https://github.com/signalwire/freeswitch/blob/master/src/mod/databases/mod_pgsql/mod_pgsql.c"
click node_sip_and_xml_profiles "https://github.com/signalwire/freeswitch/blob/master/conf/vanilla/freeswitch.xml"
click node_esl_clients "https://github.com/signalwire/freeswitch/blob/master/libs/esl/src/esl.c"
click node_build_packaging "https://github.com/signalwire/freeswitch/blob/master/configure.ac"
click node_tests "https://github.com/signalwire/freeswitch/blob/master/tests/unit/Makefile.am"
click node_vendor_libs "https://github.com/signalwire/freeswitch/blob/master/libs/srtp/CMakeLists.txt"

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_repo,node_core_runtime,node_session_channel,node_media_rtp,node_ivr_flow,node_events,node_xml_config,node_module_loader toneBlue
class node_sofia,node_other_endpoints,node_codec_modules,node_format_modules,node_app_modules,node_script_bindings,node_event_integration,node_cdr_storage toneAmber
class node_sip_and_xml_profiles,node_esl_clients,node_build_packaging,node_tests,node_vendor_libs toneMint
```

## Components

### Core

Central daemon runtime and session engine

- **FreeSWITCH**: telecom platform · Top-level application server and module ecosystem
- [Core runtime](https://github.com/signalwire/freeswitch/blob/master/src/switch_core.c): daemon core · Session lifecycle, state machine, scheduling, logging, module loading · `src/switch_core.c`
- [Sessions & channels](https://github.com/signalwire/freeswitch/blob/master/src/switch_core_session.c): call control · Per-call session, channel state, and control primitives · `src/switch_core_session.c`
- [Media engine](https://github.com/signalwire/freeswitch/blob/master/src/switch_core_media.c): media control · RTP, media bugs, jitter, packetization, and core media plumbing · `src/switch_core_media.c`
- [IVR flow](https://github.com/signalwire/freeswitch/blob/master/src/switch_ivr.c): call flow · Bridge/originate/play-say/menu helpers that implement call behavior · `src/switch_ivr.c`
- [Event bus](https://github.com/signalwire/freeswitch/blob/master/src/switch_event.c): event system · Event creation, dispatch, and hook integration for call state and telemetry · `src/switch_event.c`
- [XML config](https://github.com/signalwire/freeswitch/blob/master/src/switch_xml_config.c): config parser · XML profile and directory parsing used by the runtime and modules · `src/switch_xml_config.c`
- [Module loader](https://github.com/signalwire/freeswitch/blob/master/src/switch_loadable_module.c): plugin loader · Dynamic loading and lifecycle management for runtime modules · `src/switch_loadable_module.c`

### Modules

Loadable feature subsystems

- [mod_sofia](https://github.com/signalwire/freeswitch/blob/master/src/mod/endpoints/mod_sofia/mod_sofia.c): SIP endpoint · Primary SIP signaling stack and SIP profile handler · `src/mod/endpoints/mod_sofia/mod_sofia.c`
- [Other endpoints](https://github.com/signalwire/freeswitch/blob/master/src/mod/endpoints/mod_skinny/mod_skinny.c): endpoint plugins · Alternate call ingress/egress modules such as skinny, verto, h323, rtmp, loopback, alsa, opal · `src/mod/endpoints/mod_skinny/mod_skinny.c`
- [Codecs](https://github.com/signalwire/freeswitch/blob/master/src/mod/codecs/mod_opus/mod_opus.c): codec plugins · Codec and transcoding modules for AMR, Opus, G.729, G.722.1, VPX, and related formats · `src/mod/codecs/mod_opus/mod_opus.c`
- [Formats](https://github.com/signalwire/freeswitch/blob/master/src/mod/formats/mod_sndfile/mod_sndfile.c): file/media plugins · Audio/video format and stream handlers such as sndfile, shout, local_stream, webm, png · `src/mod/formats/mod_sndfile/mod_sndfile.c`
- [Applications](https://github.com/signalwire/freeswitch/blob/master/src/mod/applications/mod_conference/mod_conference.c): call apps · Dialplan apps like conference, voicemail, callcenter, FIFO, LCR, directory, limit, curl, db · `src/mod/applications/mod_conference/mod_conference.c`
- [Script bindings](https://github.com/signalwire/freeswitch/blob/master/src/mod/languages/mod_lua/mod_lua.cpp): language modules · Lua, Python, Perl, Java, managed, V8, basic scripting, and ASR/TTS integration · `src/mod/languages/mod_lua/mod_lua.cpp`
- [Event/API I/O](https://github.com/signalwire/freeswitch/blob/master/src/mod/event_handlers/mod_event_socket/mod_event_socket.c): integration modules · Event socket, multicast, AMQP, Erlang event, SNMP, and XML/HTTP integration points · `src/mod/event_handlers/mod_event_socket/mod_event_socket.c`
- [Data store](https://github.com/signalwire/freeswitch/blob/master/src/mod/databases/mod_pgsql/mod_pgsql.c): db/cache modules · Persistence and lookup integrations for PostgreSQL, MariaDB, SQLite, Redis, Memcache, Mongo, ODBC · `src/mod/databases/mod_pgsql/mod_pgsql.c`

### Support

Configuration, clients, libraries, build and test

- [Deployment profiles](https://github.com/signalwire/freeswitch/blob/master/conf/vanilla/freeswitch.xml): xml configs · Profile-specific autoload configs, SIP profiles, dialplans, directories, vars, and language menus · `conf/vanilla/freeswitch.xml`
- [ESL clients](https://github.com/signalwire/freeswitch/blob/master/libs/esl/src/esl.c): client library · Event Socket Library plus CLI and sample programmatic clients · `libs/esl/src/esl.c`
- [Build & packaging](https://github.com/signalwire/freeswitch/blob/master/configure.ac): tooling · Autotools/CMake, Docker, Debian/RPM, Windows solutions, and packaging scripts · `configure.ac`
- [Tests](https://github.com/signalwire/freeswitch/blob/master/tests/unit/Makefile.am): test suite · Unit and module tests for core call control, SIP/RTP, XML, codecs, VAD, and media behaviors · `tests/unit/Makefile.am`
- [Vendored libs](https://github.com/signalwire/freeswitch/blob/master/libs/srtp/CMakeLists.txt): third-party libs · Embedded dependencies such as APR, SRTP, libvpx, libyuv, opus, sofia-sip, spandsp, sndfile · `libs/srtp/CMakeLists.txt`

## Connections

- FreeSWITCH → Core runtime: contains · The daemon is implemented around the central runtime
- FreeSWITCH → Module loader: loads · Core loads runtime modules from shared libraries
- Core runtime → Sessions & channels: orchestrates · Core owns session lifecycle and channel state
- Core runtime → Media engine: controls · Core manages RTP and media processing
- Core runtime → IVR flow: invokes · IVR helpers implement call behavior on top of core session control
- Core runtime → Event bus: emits · Runtime state changes are published onto the event bus
- Core runtime → XML config: reads · Configuration and deployment data are XML-driven
- Module loader → mod_sofia: loads · SIP endpoint is a loadable module
- Module loader → Other endpoints: loads · Alternate endpoint stacks are pluggable
- Module loader → Codecs: loads · Codec implementations are built as modules
- Module loader → Formats: loads · Format and stream handlers are pluggable
- Module loader → Applications: loads · Call apps are implemented as modules
- Module loader → Script bindings: loads · Scriptable control surfaces are runtime modules
- Module loader → Event/API I/O: loads · Event and API bridges are modular
- Module loader → Data store: loads · Database and cache integrations are modular
- mod_sofia → Sessions & channels: creates · SIP ingress/egress creates sessions and channels
- Other endpoints → Sessions & channels: creates · Non-SIP endpoints hand calls into the core session engine
- Codecs → Media engine: extends · Codec modules feed the media pipeline
- Formats → Media engine: feeds · Media/file handlers supply and consume media streams
- Applications → IVR flow: implements · Applications build higher-level call logic on IVR helpers
- Script bindings → Event bus: consumes · Language bindings frequently subscribe to or emit events
- Event/API I/O → Event bus: bridges · Socket, bus, and XML/HTTP modules move events and API calls out of core
- Data store → Event bus: persists · CDR and related integrations persist event-derived data
- Deployment profiles → mod_sofia: configures · Deployment profiles define SIP profiles and module autoloading
- Deployment profiles → Applications: routes · Dialplan and directory XML steer application behavior
- ESL clients → Event/API I/O: connects · ESL clients talk to event socket and related APIs
- Build & packaging → Module loader: produces · Build system compiles the core and modules into packages
- Build & packaging → Vendored libs: vendors · Optional features depend on bundled third-party libraries
- Tests → Core runtime: verifies · Unit tests exercise the core runtime and call control
- Tests → mod_sofia: verifies · Dedicated tests cover SIP behavior and signaling flows
- Tests → Media engine: verifies · Tests cover RTP, media, codecs, and VAD behaviors
