# drachtio/drachtio-siprec-recording-server architecture

> Architecture diagram of the GitHub repository drachtio/drachtio-siprec-recording-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drachtio/drachtio-siprec-recording-server
- Repository: https://github.com/drachtio/drachtio-siprec-recording-server

## Overview

##### Project type and purpose
- This is an open-source Node.js “SIPREC recording server” that sits on top of a drachtio SIP server and routes SIPREC INVITEs to a back-end media recorder (either RTPengine or Freeswitch/Asterisk).
- Its job is to parse the multipart SIPREC INVITE, allocate media endpoints on the chosen media server, glue caller/callee media flows, and return a 200 OK to the SIPREC client so that recording begins.

##### File structure
- Top level:
- app.js – main entry-point, initializes drachtio SRF and connects handlers
- config/*.json – sample configs for RTPengine, Freeswitch/Asterisk, local tests
- lib/ – core modules:
– payload-parser.js, payload-combiner.js, utils.js
– freeswitch-call-handler.js (and rtpengine-call-handler.js)
– dtmf-event-handler.js
- test/ – test suite and Docker Compose testbed
- Notice two handler modules implementing the adapter pattern for each media server, and shared utility modules for SDP/XML parsing and message assembly.

##### Read README for additional insights
- Two mutually exclusive back-end modes: RTPengine (uses its NG control protocol over UDP, no Redis) vs Freeswitch/Asterisk (requires Redis to correlate A- and B-leg, custom dialplan for hairpin recording).
- External dependencies: drachtio SIP server, optional Redis, RTPengine or Freeswitch/Asterisk, various SBCs.

##### Detail
- Handler module as a sub-component under the Node app.
- Call out configuration files and how they select the media server mode.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    SBC["SIPREC Client / SBC"]:::external
    DRS["drachtio SIP Server"]:::external

    %% Node.js Application
    subgraph "Node.js Recording Server" 
        direction TB
        APP["app.js"]:::app
        subgraph "Core Modules"
            direction TB
            PP["payload-parser.js"]:::core
            PC["payload-combiner.js"]:::core
            UT["utils.js"]:::core
        end
        subgraph "Handler Modules"
            direction TB
            RTPH["rtpengine-call-handler.js"]:::handler
            FSH["freeswitch-call-handler.js"]:::handler
            DTMF["dtmf-event-handler.js"]:::handler
        end
        subgraph "Configuration Samples"
            direction TB
            CR1["default.json.example-rtpengine"]:::config
            CR2["default.json.example-freeswitch"]:::config
            CL1["local-test.json"]:::config
            CL2["local-test2.json"]:::config
            CL3["local-test3.json"]:::config
        end
    end

    %% Media Servers & Data Stores
    subgraph "Media Servers"
        direction TB
        RTPENG["RTPengine NG Control"]:::media
        FSA["FreeSWITCH/Asterisk Dialplan"]:::media
    end
    REDIS["Redis"]:::datastore
    PCAP["PCAP Storage"]:::datastore
    STORAGE["Post-processing (flac/wav/mp3)"]:::datastore

    %% Test Infrastructure
    subgraph "Test Suite & Fixtures"
        direction TB
        TESTIDX["test/index.js"]:::test
        subgraph "Test Modules"
            direction TB
            TST1["parser.js"]:::test
            TST2["call_tests.js"]:::test
        end
        subgraph "Test Data"
            direction TB
            TD1["test/data/"]:::test
            TD2["test/scenarios/pcap/"]:::test
        end
        TDCOMP["docker-compose-testbed.yaml"]:::test
        TSTART["docker_start.js"]:::test
        TSTOP["docker_stop.js"]:::test
    end

    %% Control Flow
    SBC -->|"SIP INVITE"| DRS
    DRS -->|"SIP INVITE"| APP
    APP -->|"parse SDP/XML"| PP
    PP --> PC
    PC --> UT

    %% RTPengine Path
    APP -->|"select RTPengine"| RTPH
    RTPH -->|"NGCP/UDP"| RTPENG
    RTPENG -->|"save PCAP"| PCAP
    PCAP --> STORAGE

    %% Freeswitch/Asterisk Path
    APP -->|"select FS/Asterisk"| FSH
    FSH -->|"SIP INVITE"| FSA
    FSA -->|"hairpin INVITE"| APP
    APP -->|"200 OK"| FSA
    FSA -->|"media & correlate"| REDIS
    REDIS --> FSH
    FSA -->|"recordings"| PCAP
    PCAP --> STORAGE

    %% Final Response
    APP -->|"200 OK SIPREC"| DRS
    DRS -->|"200 OK SIPREC"| SBC

    %% Click Events
    click APP "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/app.js"
    click CR1 "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/config/default.json.example-rtpengine"
    click CR2 "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/config/default.json.example-freeswitch"
    click CL1 "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/config/local-test.json"
    click CL2 "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/config/local-test2.json"
    click CL3 "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/config/local-test3.json"
    click PP "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/lib/payload-parser.js"
    click PC "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/lib/payload-combiner.js"
    click UT "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/lib/utils.js"
    click RTPH "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/lib/rtpengine-call-handler.js"
    click FSH "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/lib/freeswitch-call-handler.js"
    click DTMF "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/lib/dtmf-event-handler.js"
    click TESTIDX "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/test/index.js"
    click TST1 "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/test/parser.js"
    click TST2 "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/test/call_tests.js"
    click TD1 "https://github.com/drachtio/drachtio-siprec-recording-server/tree/main/test/data/"
    click TD2 "https://github.com/drachtio/drachtio-siprec-recording-server/tree/main/test/scenarios/pcap/"
    click TDCOMP "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/test/docker-compose-testbed.yaml"
    click TSTART "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/test/docker_start.js"
    click TSTOP "https://github.com/drachtio/drachtio-siprec-recording-server/blob/main/test/docker_stop.js"
    click TESTIDX "https://github.com/drachtio/drachtio-siprec-recording-server/tree/main/test/"

    %% Styles
    classDef external fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef app fill:#E6FFEA,stroke:#2C662D,color:#2C662D
    classDef core fill:#E6FFEA,stroke:#2C662D,color:#2C662D
    classDef handler fill:#E6FFEA,stroke:#2C662D,color:#2C662D
    classDef config fill:#E6FFEA,stroke:#2C662D,color:#2C662D
    classDef media fill:#FFE7C6,stroke:#D9822B,color:#D9822B
    classDef datastore fill:#F5E6D3,stroke:#8B4513,color:#8B4513
    classDef test fill:#F0EFF5,stroke:#5A4E7C,color:#5A4E7C
```
