# opensips/opensips-softswitch-ce architecture

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

- Interactive diagram: https://gitdiagram.com/opensips/opensips-softswitch-ce
- Repository: https://github.com/opensips/opensips-softswitch-ce

## Overview

##### Project type and purpose
- This is a full-blown SIP SoftSwitch platform, delivered as a set of cooperating Docker containers.
- Purpose: provide SIP proxying (OpenSIPS), media services (FreeSWITCH, RTPProxy), a web control panel (OpenSIPS-CP), persistent storage (MySQL), and optional call-flow visualization (Homer).

##### File structure
- Top-level: docker-compose.yml orchestrates all services.
- etc/opensips, etc/opensips-cp, etc/freeswitch, etc/mysql: each directory holds container initialization and configuration scripts.
- docs/: describes components, provisioning, testing, and how they interact.
- tests/: SIPSsert scenarios driving SIP UAs through OpenSIPS and validating behavior.

##### README
- Lists core components: OpenSIPS SIP proxy, RTPProxy, FreeSWITCH for voicemail/announcements, MySQL for database, OpenSIPS Control Panel (PHP), optional Homer for SIP trace capture.
- Explains how Docker Compose brings them up, where to configure IPs, how provisioning and tests run.

a. Main components
- Docker Host (the machine running Docker).
- Docker Compose network connecting:
- OpenSIPS SIP Proxy
- MySQL Database
- OpenSIPS Control Panel (Web UI)
- RTPProxy (media relay)
- FreeSWITCH (media services: voicemail/announcements)
- Optional: Homer Server (call capture & visualization)
- External SIP endpoints (User Agents, PSTN gateways)

b. Relationships & interactions
- SIP UA ↔ SIP Proxy: UDP/TCP signaling.
- SIP Proxy ↔ Database: reads/writes user credentials, dial plans, ACL flags via MySQL.
- SIP Proxy ↔ RTPProxy: instructs relay for media packets.
- SIP Proxy ↔ FreeSWITCH: hands off calls for voicemail or announcement services.
- Control Panel ↔ Database: CRUD operations for provisioning subscribers, domains, dialplans, ACLs.
- Homer ↔ OpenSIPS: receives SIP call detail records for visualization.
- SIP Proxy ↔ PSTN Gateway: external trunk for outbound/inbound PSTN.

c. Architectural patterns & principles
- Micro-services style using Docker Compose for isolation of control plane (CP, DB) vs data plane (OpenSIPS, RTPProxy, FreeSWITCH).
- Clear separation of concerns:
- Signaling (OpenSIPS),
- Media relay (RTPProxy),
- Media application (FreeSWITCH),
- Persistence (MySQL),
- Presentation (CP, Homer).
- Infrastructure-as-code and container initialization scripts for reproducible provisioning.

d. Key technologies/frameworks
- OpenSIPS (event-driven C SIP server)
- MySQL (InnoDB)
- PHP + Apache/Nginx (OpenSIPS-CP)
- RTPProxy (C RTP relay)
- FreeSWITCH (C media server)
- Homer (Elasticsearch/Graphana based SIP-RT-capture)
- Docker & Docker Compose

##### Detail level
- Inter-container network links defined in docker-compose.yml.
- Initialization order or dependencies indicated by entrypoint scripts in etc/.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    subgraph "External"
        direction TB
        SIP_UA["SIP User Agent"]:::external
        PSTN_GW["PSTN Gateway"]:::external
        SIPSsert["SIP Testing Harness"]:::external
        subgraph "Documentation"
            direction TB
            DocsComponents["Components"]:::docs
            DocsGetting["Getting Started"]:::docs
            DocsProvision["Provisioning"]:::docs
            DocsTesting["Testing"]:::docs
        end
    end

    %% Docker Network Boundary
    subgraph "Docker Network" 
        direction TB

        %% Control Plane
        subgraph "Control Plane"
            direction TB
            ControlPanel["OpenSIPS Control Panel (Web UI)"]:::control
            MySQL["MySQL Database"]:::control
        end

        %% Data Plane
        subgraph "Data Plane"
            direction TB
            OpenSIPS["OpenSIPS SIP Proxy\n(5060 UDP/TCP)"]:::data
            RTPProxy["RTPProxy Media Relay"]:::data
            FreeSWITCH["FreeSWITCH Media Server"]:::data
        end

        %% Observability
        subgraph "Observability"
            direction TB
            Homer["Homer Call Capture"]:::obs
        end
    end

    %% Connections
    SIP_UA -->|"SIP signaling"| OpenSIPS
    PSTN_GW -->|"SIP signaling"| OpenSIPS
    SIPSsert -->|"SIP scenarios"| OpenSIPS

    OpenSIPS -->|"Reads/Writes"| MySQL
    ControlPanel -->|"CRUD operations"| MySQL

    OpenSIPS -->|"media relay instructions"| RTPProxy
    OpenSIPS -->|"call handoff"| FreeSWITCH

    OpenSIPS -->|"SIP CDRs"| Homer

    %% Documentation Links
    DocsComponents -->|refers to| ControlPanel
    DocsGetting -->|starts with| dockerCompose
    DocsProvision -->|initial scripts| MySQL
    DocsTesting -->|drives| SIPSsert

    %% Click Events
    click dockerCompose "https://github.com/opensips/opensips-softswitch-ce/blob/main/docker-compose.yml"
    click OpenSIPS "https://github.com/opensips/opensips-softswitch-ce/tree/main/etc/opensips"
    click MySQL "https://github.com/opensips/opensips-softswitch-ce/tree/main/etc/mysql"
    click ControlPanel "https://github.com/opensips/opensips-softswitch-ce/tree/main/etc/opensips-cp"
    click FreeSWITCH "https://github.com/opensips/opensips-softswitch-ce/tree/main/etc/freeswitch"
    click RTPProxy "https://github.com/opensips/opensips-softswitch-ce/blob/main/etc/mysql/10_config_rtpproxy.sh"
    click Homer "https://github.com/opensips/opensips-softswitch-ce/blob/main/docs/homer.md"
    click SIPSsert "https://github.com/opensips/opensips-softswitch-ce/tree/main/tests/"
    click DocsComponents "https://github.com/opensips/opensips-softswitch-ce/blob/main/docs/components.md"
    click DocsGetting "https://github.com/opensips/opensips-softswitch-ce/blob/main/docs/getting-started.md"
    click DocsProvision "https://github.com/opensips/opensips-softswitch-ce/blob/main/docs/provisioning.md"
    click DocsTesting "https://github.com/opensips/opensips-softswitch-ce/blob/main/docs/testing.md"

    %% Styles
    classDef control fill:#cce5ff, stroke:#004085, color:#004085
    classDef data fill:#d4edda, stroke:#155724, color:#155724
    classDef obs fill:#fff3cd, stroke:#856404, color:#856404
    classDef external fill:#e2e3e5, stroke:#6c757d, color:#6c757d
    classDef docs fill:#f8d7da, stroke:#721c24, color:#721c24
```
