# alessandrovezzoso/portunus architecture

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

- Interactive diagram: https://gitdiagram.com/alessandrovezzoso/portunus
- Repository: https://github.com/alessandrovezzoso/portunus

## Overview

Portunus is a Go SIP answering service for a Yeastar PBX. The documented call flow is PBX-routed call → greeting → listen and transcribe → Claude reply → synthesize and play audio → end call. Its runtime also includes G.711/audio handling, configuration, and speech-service adapters. The README documents the conversational workflow, while the sampled call code shows the listen/transcription path; unsampled conversation details are represented only where the README supports them.

Main entry points: [`internal/call/listen.go`](https://github.com/alessandrovezzoso/portunus/blob/main/internal/call/listen.go) (Listen and transcribe), [`internal/sip/call.go`](https://github.com/alessandrovezzoso/portunus/blob/main/internal/sip/call.go) (Call handling), [`internal/call/greet.go`](https://github.com/alessandrovezzoso/portunus/blob/main/internal/call/greet.go) (Fixed greeting), [`internal/call`](https://github.com/alessandrovezzoso/portunus/tree/main/internal/call) (Conversation turn)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and configuration"]
  node_main["Runtime wiring<br/>[main.go]"]
  node_preflight["Preflight checks<br/>[preflight.go]"]
  node_config["Configuration<br/>[config.go]"]
  node_dotenv["Dotenv reader<br/>[dotenv.go]"]
end

subgraph group_telephony["SIP telephony"]
  node_sipserver["SIP server<br/>[server.go]"]
  node_sipcall["Call handling<br/>[call.go]"]
end

subgraph group_conversation["Call and audio"]
  node_greeting["Fixed greeting<br/>[greet.go]"]
  node_listen["Listen and transcribe<br/>[listen.go]"]
  node_segmenter["Utterance segmenter<br/>[segmenter.go]"]
  node_media["Audio conversion<br/>[decoder.go]"]
  node_pacer["RTP audio pacer<br/>[pacer.go]"]
  node_vad["Silero VAD<br/>[silero.go]"]
  node_conversationturn["Conversation turn"]
end

subgraph group_speech["Speech services"]
  node_sttadapter["STT adapter<br/>[client.go]"]
  node_whisper["Whisper service"]
  node_ttsadapter["TTS adapter<br/>[client.go]"]
  node_kokoro["Kokoro service"]
end

node_caller(("Caller"))
node_pbx["Yeastar S20"]
node_claude["Claude API"]

node_caller -->|"calls office"| node_pbx
node_pbx -->|"routes SIP call"| node_sipserver
node_main -->|"loads settings"| node_config
node_main -->|"checks readiness"| node_preflight
node_main -->|"starts server"| node_sipserver
node_sipserver -->|"handles INVITE"| node_sipcall
node_sipcall -->|"runs handler"| node_greeting
node_sipcall -->|"runs handler"| node_listen
node_sipcall -->|"answers call"| node_caller
node_greeting -->|"requests speech"| node_ttsadapter
node_ttsadapter -->|"synthesizes text"| node_kokoro
node_greeting -->|"encodes audio"| node_media
node_greeting -->|"queues audio"| node_pacer
node_listen -->|"decodes audio"| node_media
node_listen -->|"checks speech"| node_vad
node_listen -->|"segments utterances"| node_segmenter
node_listen -->|"transcribes utterances"| node_sttadapter
node_sttadapter -->|"uploads WAV"| node_whisper
node_listen -.->|"provides transcript"| node_conversationturn
node_conversationturn -->|"sends turn text"| node_claude
node_claude -->|"streams reply"| node_conversationturn
node_conversationturn -.->|"synthesizes reply"| node_ttsadapter
node_ttsadapter -.->|"streams audio"| node_pacer
node_pacer -->|"writes RTP audio"| node_sipcall
node_sipcall -->|"signals hangup"| node_pbx
node_dotenv -->|"parses environment"| node_config

click node_main "https://github.com/alessandrovezzoso/portunus/blob/main/cmd/portunus/main.go"
click node_preflight "https://github.com/alessandrovezzoso/portunus/blob/main/cmd/portunus/preflight.go"
click node_config "https://github.com/alessandrovezzoso/portunus/blob/main/internal/config/config.go"
click node_dotenv "https://github.com/alessandrovezzoso/portunus/blob/main/internal/config/dotenv.go"
click node_sipserver "https://github.com/alessandrovezzoso/portunus/blob/main/internal/sip/server.go"
click node_sipcall "https://github.com/alessandrovezzoso/portunus/blob/main/internal/sip/call.go"
click node_greeting "https://github.com/alessandrovezzoso/portunus/blob/main/internal/call/greet.go"
click node_listen "https://github.com/alessandrovezzoso/portunus/blob/main/internal/call/listen.go"
click node_segmenter "https://github.com/alessandrovezzoso/portunus/blob/main/internal/call/segmenter.go"
click node_media "https://github.com/alessandrovezzoso/portunus/blob/main/internal/media/decoder.go"
click node_pacer "https://github.com/alessandrovezzoso/portunus/blob/main/internal/media/pacer.go"
click node_vad "https://github.com/alessandrovezzoso/portunus/blob/main/internal/vad/silero/silero.go"
click node_sttadapter "https://github.com/alessandrovezzoso/portunus/blob/main/internal/stt/openaicompat/client.go"
click node_ttsadapter "https://github.com/alessandrovezzoso/portunus/blob/main/internal/tts/openaicompat/client.go"
click node_conversationturn "https://github.com/alessandrovezzoso/portunus/tree/main/internal/call"

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_main,node_preflight,node_config,node_dotenv toneBlue
class node_sipserver,node_sipcall toneAmber
class node_greeting,node_listen,node_segmenter,node_media,node_pacer,node_vad,node_conversationturn,node_claude toneMint
class node_sttadapter,node_whisper,node_ttsadapter,node_kokoro toneRose
class node_caller,node_pbx toneIndigo
```

## Components

### Runtime and configuration

- [Runtime wiring](https://github.com/alessandrovezzoso/portunus/blob/main/cmd/portunus/main.go): `cmd/portunus/main.go`
- [Preflight checks](https://github.com/alessandrovezzoso/portunus/blob/main/cmd/portunus/preflight.go): `cmd/portunus/preflight.go`
- [Configuration](https://github.com/alessandrovezzoso/portunus/blob/main/internal/config/config.go): `internal/config/config.go`
- [Dotenv reader](https://github.com/alessandrovezzoso/portunus/blob/main/internal/config/dotenv.go): `internal/config/dotenv.go`

### SIP telephony

- [SIP server](https://github.com/alessandrovezzoso/portunus/blob/main/internal/sip/server.go): `internal/sip/server.go`
- [Call handling](https://github.com/alessandrovezzoso/portunus/blob/main/internal/sip/call.go): `internal/sip/call.go`

### Call and audio

- [Fixed greeting](https://github.com/alessandrovezzoso/portunus/blob/main/internal/call/greet.go): `internal/call/greet.go`
- [Listen and transcribe](https://github.com/alessandrovezzoso/portunus/blob/main/internal/call/listen.go): `internal/call/listen.go`
- [Utterance segmenter](https://github.com/alessandrovezzoso/portunus/blob/main/internal/call/segmenter.go): `internal/call/segmenter.go`
- [Audio conversion](https://github.com/alessandrovezzoso/portunus/blob/main/internal/media/decoder.go): `internal/media/decoder.go`
- [RTP audio pacer](https://github.com/alessandrovezzoso/portunus/blob/main/internal/media/pacer.go): `internal/media/pacer.go`
- [Silero VAD](https://github.com/alessandrovezzoso/portunus/blob/main/internal/vad/silero/silero.go): `internal/vad/silero/silero.go`
- [Conversation turn](https://github.com/alessandrovezzoso/portunus/tree/main/internal/call): `internal/call`

### Speech services

- [STT adapter](https://github.com/alessandrovezzoso/portunus/blob/main/internal/stt/openaicompat/client.go): `internal/stt/openaicompat/client.go`
- **Whisper service**
- [TTS adapter](https://github.com/alessandrovezzoso/portunus/blob/main/internal/tts/openaicompat/client.go): `internal/tts/openaicompat/client.go`
- **Kokoro service**

### Other components

- **Caller**
- **Yeastar S20**
- **Claude API**

## Connections

- Caller → Yeastar S20: calls office (evidence: `README.md`)
- Yeastar S20 → SIP server: routes SIP call (evidence: `README.md`)
- Runtime wiring → Configuration: loads settings (evidence: `cmd/portunus/main.go`)
- Runtime wiring → Preflight checks: checks readiness (evidence: `cmd/portunus/main.go`)
- Runtime wiring → SIP server: starts server (evidence: `cmd/portunus/main.go`)
- SIP server → Call handling: handles INVITE (evidence: `internal/sip/call.go`)
- Call handling → Fixed greeting: runs handler (evidence: `internal/call/greet.go`)
- Call handling → Listen and transcribe: runs handler (evidence: `internal/call/listen.go`)
- Call handling → Caller: answers call (evidence: `README.md`)
- Fixed greeting → TTS adapter: requests speech (evidence: `internal/call/greet.go`)
- TTS adapter → Kokoro service: synthesizes text (evidence: `internal/tts/openaicompat/client.go`)
- Fixed greeting → Audio conversion: encodes audio (evidence: `internal/call/greet.go`)
- Fixed greeting → RTP audio pacer: queues audio (evidence: `internal/call/greet.go`)
- Listen and transcribe → Audio conversion: decodes audio (evidence: `README.md`)
- Listen and transcribe → Silero VAD: checks speech (evidence: `README.md`)
- Listen and transcribe → Utterance segmenter: segments utterances (evidence: `internal/call/listen.go`)
- Listen and transcribe → STT adapter: transcribes utterances (evidence: `internal/call/listen.go`)
- STT adapter → Whisper service: uploads WAV (evidence: `internal/stt/openaicompat/client.go`)
- Listen and transcribe → Conversation turn: provides transcript
- Conversation turn → Claude API: sends turn text (evidence: `README.md`)
- Claude API → Conversation turn: streams reply (evidence: `README.md`)
- Conversation turn → TTS adapter: synthesizes reply
- TTS adapter → RTP audio pacer: streams audio
- RTP audio pacer → Call handling: writes RTP audio (evidence: `README.md`)
- Call handling → Yeastar S20: signals hangup (evidence: `README.md`)
- Dotenv reader → Configuration: parses environment (evidence: `internal/config/dotenv.go`)
