# SignaGo

**Repository Path**: nowuser118/signa-go

## Basic Information

- **Project Name**: SignaGo
- **Description**: 核心架构：基于 DDD 四层架构，实现业务逻辑与底层通信协议（SIP/ESL）的深度解耦。
媒体能力：支持 Kamailio + RTPEngine 的集群化媒体代理，以及多节点 FreeSWITCH 的动态调度。
AI 赋能：内置 ASR 流式处理引擎，支持对接 DeepSeek、OpenAI 等大模型实现实时坐席 Copilot 与通话深度语义分析。
可观测性：全链路 OpenTelemetr
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="right">
  <a href="README.md">English</a> | <a href="README_ZH.md">简体中文</a>
</p>

<p align="center">
  <img src="docs/images/logo.png" width="160" alt="SignaGo Logo">
</p>

<h1 align="center">SignaGo</h1>

<p align="center">
  <strong>High-Performance Cloud-Native Intelligent PBX Platform</strong>
</p>

<p align="center">
  <a href="https://go.dev"><img src="https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go" alt="Go Version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://github.com/tangyu-dch/signa-go"><img src="https://img.shields.io/github/stars/tangyu-dch/signa-go?style=social" alt="GitHub Stars"></a>
</p>

---

**SignaGo** is a production-ready, cloud-native PBX platform designed for carrier-grade scenarios. Built with **Go 1.24** and following strict **DDD (Domain-Driven Design)** principles, it seamlessly integrates **Kamailio**'s high-performance routing with **FreeSWITCH**'s sophisticated media processing via a modular plugin architecture.

> [!WARNING]
> **Legal Disclaimer and Compliance Advice**
> 1. **Prohibited Use**: This system is strictly for legal internal communications. Users are prohibited from illegal activities.
> 2. **User Responsibility**: All legal consequences are the sole responsibility of the user.
> 3. **Security Auditing**: Cooperate with local authorities for traffic auditing.

---

## 📋 Table of Contents

- [Architecture](#-architecture)
- [Features](#-features)
- [Tech Stack](#-tech-stack)
- [Quick Start](#-quick-start)
- [Configuration](#-configuration)
- [Plugin System](#-plugin-system)
- [Observability](#-observability)
- [Development Guide](#-development-guide)

---

## 🏛 Architecture

The system follows strict **DDD (Domain-Driven Design)** layering:

```
┌────────────────────────────────────────────────────┐
│             Interfaces Layer                        │
│      HTTP RESTful API │ WebSocket │ Metrics         │
├────────────────────────────────────────────────────┤
│            Application Layer                        │
│  Routing │ IVR Engine │ Billing │ Event Handlers    │
├────────────────────────────────────────────────────┤
│              Domain Layer                           │
│         Business Models │ Repository Interfaces     │
├────────────────────────────────────────────────────┤
│           Infrastructure Layer                      │
│   GORM/MySQL │ Redis │ Kamailio ESL │ S3 Storage    │
└────────────────────────────────────────────────────┘
```

```mermaid
graph LR
    SIP_Client --> Kamailio
    Kamailio -->|ESL/EVAPI| SignaGo_Backend
    SignaGo_Backend --> MySQL
    SignaGo_Backend --> Redis
    SignaGo_Backend --> FreeSWITCH
    SignaGo_Backend -->|S3| RustFS_MinIO
    Admin -->|HTTPS| React_Frontend
    React_Frontend -->|REST/WS| SignaGo_Backend
```

---

## 🚀 Feature Architecture Map

SignaGo employs a modular, high-performance distributed architecture, covering full-stack capabilities from basic communication to advanced business intelligence.

### 📡 Core Engine & Orchestration
- **Multi-Engine Orchestration** — Deep integration with Kamailio (Signaling), RTPEngine (Media Proxy), and FreeSWITCH (Media Processing).
- **Distributed High Availability** — Stateless design with Redis global state synchronization, supporting carrier-grade horizontal scaling.
- **Real-time Event Bus** — Millisecond-level call monitoring and event push via WebSocket and EVAPI.

### 🛣️ Smart Routing & Selection
- **Multi-dimensional Routing** — Supports Longest Prefix Match (LPM), Time-based, Inbound DID mapping, and internal extension routing.
- **Dynamic Selection (LCR)** — Intelligent calculation of the lowest cost path with gateway group load balancing and priority failover.
- **Number Pool Management** — Flexible caller/callee rewrite rules with random, round-robin, weighted, and area-code-based selection.

### 💳 Billing & Resource Control
- **Real-time Control** — Supports Pre-paid and Post-paid modes with millisecond-level balance verification and CPS/Concurrency limits.
- **Multi-tier Rate Management** — Flexibly define customer and supplier rates with various increments (1s/6s/60s/60+6).
- **Risk Defense** — System-wide global blacklists, regex-based prefix filtering, and anomalous call behavior interception (Fraud Detection).

### 📊 Advanced Analytics & BI
- **Deep Business Insights** — Includes gateway analysis, account statistics, daily profit summaries, SIP status code analysis, and regional heatmaps.
- **Real-time Dashboard** — Provides ASR/ACD/PDD fluctuation curves and 24-hour call trend analysis.
- **Professional Export** — Full module support for professional Excel report export for enterprise-level financial auditing.

### 🧠 AI & Intelligence
- **Agent Copilot** — Real-time coaching, sentiment analysis, and intent recognition during calls via ASR/LLM.
- **Automated Summaries** — Generates executive summaries, customer profiles, and follow-up task suggestions after calls.
- **Streaming Pipeline** — High-performance audio sampling for multi-engine ASR parallel processing and real-time transcription.

### 🏢 Enterprise Suite
- **Visual IVR** — Drag-and-drop designer based on ReactFlow with support for DTMF, Voice interaction, and dynamic Webhook branches.
- **Intelligent Call Center** — Advanced queuing algorithms (ACD), agent recording management, and full life-cycle event synchronization.
- **Cloud-Native Ready** — Local or S3 (MinIO/OSS) recording storage with role-based access control (RBAC) auditing.

---

## 🛠 Tech Stack

| Layer | Technology |
|-------|-----------|
| Backend | Go 1.24+ |
| Web Framework | Gin |
| ORM | GORM |
| Database | MySQL 8.0+ / SQLite |
| Cache | Redis (3-tier: Local LRU + Redis + Preload) |
| SIP Core | Kamailio (JSON-RPC + EVAPI) |
| Media | FreeSWITCH (ESL Outbound) / RTPEngine |
| Object Storage | S3-compatible (RustFS / MinIO) |
| Frontend | React 18 + TypeScript + Vite |
| UI Library | Ant Design 5 |
| State Management | Zustand + TanStack Query |
| Visualization | ReactFlow (IVR) + ECharts (Analytics) |
| Observability | Prometheus Metrics + OpenTelemetry Tracing |
| Containers | Docker + docker-compose |

---

## 🚀 Quick Start

### Prerequisites

| Dependency | Version | Notes |
|-----------|---------|-------|
| Go | 1.24+ | Backend runtime |
| Node.js | 18+ | Frontend build |
| Yarn | 1.x | Frontend package manager |
| MySQL | 8.0+ | Primary database (SQLite also supported) |
| Redis | 6.0+ | Cache and sessions |
| Kamailio | 5.x | SIP core (optional) |
| FreeSWITCH | 1.10+ | Media processing (optional) |

### Step 1 — Clone

**GitHub (Recommended)**:
```bash
git clone https://github.com/tangyu-dch/signa-go.git
cd signa-go
```

**Gitee (Mirror for China)**:
```bash
git clone https://gitee.com/sc-tanyo/signa-go.git
cd signa-go
```

### Step 2 — Configure

```bash
cp configs/config.yaml.example configs/config.yaml
```

Edit `configs/config.yaml`. At minimum, set:

```yaml
database:
  host: "localhost"
  username: "root"
  password: "your-password"
  database: "signa-go"

server:
  jwt_secret: "your-secret-key-change-in-production"
```

### Step 3 — Install Dependencies

```bash
make install                     # Go modules
cd frontend && yarn install && cd ..  # Frontend packages
```

### Step 4 — Initialize Database

```bash
# GORM AutoMigrate runs automatically on first start.
# This seeds initial permissions, admin accounts, and system config:
make seed
```

### Step 5 — One-Click Start

```bash
# Starts backend (:8090) + frontend (:3000) in background
make start
```

Access after start:
- **Frontend Console** → http://localhost:3000
- **Backend API** → http://localhost:8090
- **Swagger UI** → http://localhost:8090/swagger/index.html

Default admin: `admin` / `admin123`

---

## ⚙️ Configuration

Full config reference for `configs/config.yaml`:

### Server

```yaml
server:
  host: ""            # Listen address, empty = 0.0.0.0
  port: 8090          # HTTP service port
  mode: "release"     # debug | release
  jwt_secret: "..."   # Change this in production!
  ivr_addr: ":8022"   # IVR ESL Outbound listen address
```

### Database

```yaml
database:
  driver: "mysql"     # mysql | postgres | sqlite
  host: "localhost"
  port: 3306
  username: "root"
  password: "signa-go@2026"
  database: "signa-go"
  log_level: "warn"   # silent | error | warn | info
```

### Redis

```yaml
redis:
  addr: "localhost:6379"
  password: ""
  db: 0
  enabled: true
```

### 3-Tier Cache

```yaml
cache:
  enabled: true
  l1_size: 10000       # Local LRU capacity (items)
  l1_ttl: 5m
  l2_ttl: 30m          # Redis TTL
  preload_enable: true
  preload_keys:
    - "gateway:*"
    - "route:*"
    - "caller_pool:*"
```

### S3 Object Storage

```yaml
s3:
  enabled: true
  endpoint: "http://localhost:9000"
  bucket: "recordings"
  access_key: "your-key"
  secret_key: "your-secret"
```

### LLM Providers

```yaml
llm:
  default_provider: "openai"
  providers:
    openai:
      api_key: "sk-..."
      base_url: "https://api.openai.com/v1"
      model: "gpt-4o"
    aliyun:
      api_key: "your-qwen-key"
      model: "qwen-max"
```

---

## 📦 Make Command Reference

### 🚦 Service Management

| Command | Description |
|---------|-------------|
| `make start` | **One-click start**: stop existing instances, then launch backend + frontend in background |
| `make stop` | **Stop all**: kill processes via PID files |
| `make restart` | **Restart all**: equivalent to `stop` + `start` |
| `make status` | **Check status**: show whether backend and frontend are running |

```bash
make start    # Start everything
make status   # Check if services are up
make restart  # Restart
make stop     # Stop everything
```

### 📋 Logs

| Command | Description |
|---------|-------------|
| `make logs` | Tail both backend + frontend logs live |
| `make logs-backend` | Backend log only (`.logs/backend.log`) |
| `make logs-frontend` | Frontend log only (`.logs/frontend.log`) |

### 🔨 Build & Run

| Command | Description |
|---------|-------------|
| `make build` | Compile binary to `build/signa-go` |
| `make run` | Build and run in foreground (production) |
| `make dev` | `go run` in foreground (development) |
| `make watch` | Hot-reload with [air](https://github.com/air-verse/air) |

### 🗄 Database

| Command | Description |
|---------|-------------|
| `make seed` | Seed initial permissions, admin users, and system config |
| `make migrate-up` | Run golang-migrate up |
| `make migrate-down` | Run golang-migrate down |

### 🧪 Code Quality

| Command | Description |
|---------|-------------|
| `make test` | Run all unit and integration tests |
| `make fmt` | Format code with `go fmt` |
| `make lint` | Static analysis with `golangci-lint` |
| `make install` | Download and tidy Go modules |
| `make clean` | Remove build artifacts |

### 🐳 Docker

| Command | Description |
|---------|-------------|
| `make docker-build` | Build Docker image |
| `make docker-run` | Run Docker container |

---

## 🧩 Plugin System

All extension features are implemented as plugins under `plugin/`:

| Plugin | Directory | Description |
|--------|-----------|-------------|
| **IVR Engine** | `plugin/ivr/` | **Core IVR state machine and node scheduling** (registered as a plugin) |
| FreeSWITCH | `plugin/freeswitch/` | ESL Outbound driver for IVR node execution (playback/TTS/DTMF) |
| ASR | `plugin/asr/` | Streaming speech recognition via mod_audio_fork |
| LLM | `plugin/llm/` | OpenAI / Qwen adapters for AI dialog nodes |
| Billing | `plugin/billing/` | Call billing and financial reports |
| Queue | `plugin/queue/` | ACD and skill-based routing |
| Media/Recording | `plugin/media/` | Recording policies and S3 upload |
| Fraud Detection | `plugin/fraud/` | Anomalous call detection |
| Notification | `plugin/notification/` | Multi-channel notification push |
| Analytics | `plugin/analytics/` | Call data aggregation and analysis |
| Storage | `plugin/storage/` | S3 local/cloud adapter |

### Writing a Custom Plugin

Implement the `plugin.Plugin` interface:

```go
type Plugin interface {
    Name() string
    Init(ctx context.Context, cfg *config.Config) error
    Stop(ctx context.Context) error
}
```

---

## 🌐 Frontend

The frontend lives in `frontend/`, built with React 18 + TypeScript + Vite.

### Standalone Start

```bash
cd frontend
yarn install
yarn dev    # → http://localhost:3000
```

### Theme System

CSS variable-driven theming with light / dark / system modes:

```tsx
import { useTheme } from '@/hooks/useTheme'

const { isDark, theme, setTheme } = useTheme()
```

Use CSS variables instead of hard-coded colors:

```css
.my-component {
  background: var(--color-bg-container);
  color: var(--color-text-primary);
}
```

See [`frontend/THEME_SYSTEM.md`](frontend/THEME_SYSTEM.md) for the full design token reference.

---

## 📖 API Documentation

After starting the server, visit:
```
http://localhost:8090/swagger/index.html
```

Key API modules:

| Module | Prefix | Description |
|--------|--------|-------------|
| Auth | `/api/v1/auth` | Login, token refresh |
| Dashboard | `/api/v1/admin/dashboard` | Real-time statistics |
| Gateways | `/api/v1/admin/gateways` | SIP gateway CRUD |
| Routes | `/api/v1/admin/routes` | Outbound routing rules |
| Numbers | `/api/v1/admin/numbers` | Number resource management |
| Caller Pools | `/api/v1/admin/caller-pools` | Number pools and selection |
| IVR | `/api/v1/admin/ivr` | IVR flow management |
| CDR | `/api/v1/admin/cdrs` | Call detail records |
| Recordings | `/api/v1/admin/recordings` | Recording files and policies |
| Billing | `/api/v1/admin/billing` | Account balance and top-up |
| Users | `/api/v1/admin/users` | Admin user management |
| Roles | `/api/v1/admin/roles` | RBAC roles and permissions |
| Notifications | `/api/v1/admin/notifications` | Notification sending and config |
| Live Calls | `/api/v1/admin/calls` | Active call monitoring |

---

## 📊 Observability

### Prometheus Metrics

```
GET http://localhost:8090/metrics
```

Key metrics:
- `signa-go_active_calls` — Current active calls
- `signa-go_call_duration_seconds` — Call duration histogram
- `signa-go_route_decisions_total` — Route decision counter
- `signa-go_billing_amount_total` — Total billed amount

### Distributed Tracing (OpenTelemetry)

```yaml
tracing:
  enabled: true
  sample_rate: 0.1        # 10% sampling for production
  export_format: "jaeger" # stdout | jaeger | zipkin
  export_target: "http"
```

---

## 🐳 Docker Deployment

### docker-compose (recommended)

```bash
cd deployments
docker-compose up -d
```

### Manual

```bash
make docker-build
make docker-run
```

### Production Checklist

- [ ] Change `jwt_secret` in config
- [ ] Set strong database password
- [ ] Set `log.format: "json"` for ELK/Loki ingestion
- [ ] Lower `tracing.sample_rate` to `0.05`–`0.1`
- [ ] Enable Redis AOF persistence

---

## 📁 Project Structure

```
signa-go/
├── cmd/
│   ├── server/          # Main entry point
│   └── seed_db/         # Database seed tool
├── configs/
│   └── config.yaml      # Main config file
├── internal/
│   ├── interfaces/      # HTTP routes and WebSocket handlers
│   ├── application/     # Application services (routing, billing, events)
│   ├── domain/          # Domain models and repository interfaces
│   └── infrastructure/  # GORM, Redis, ESL implementations
├── plugin/              # Plugin system
│   ├── freeswitch/      # FreeSWITCH ESL driver
│   ├── ivr/             # IVR execution engine
│   ├── asr/             # Speech recognition
│   ├── llm/             # LLM adapters
│   ├── billing/         # Billing plugin
│   ├── queue/           # Queue management
│   ├── fraud/           # Fraud detection
│   └── notification/    # Notification push
├── frontend/            # React frontend
│   └── src/
│       ├── api/         # API client layer
│       ├── pages/       # Page components
│       └── styles/      # Theme and global styles
├── docs/                # Documentation
├── deployments/         # docker-compose and deployment configs
├── Makefile             # Build and ops commands
└── Dockerfile
```

---

## 👨‍💻 Development Guide

### Code Standards

```bash
make fmt    # Format before committing
make lint   # Static analysis
make test   # Run tests
```

### Adding a New API Endpoint

1. Define model and repository interface in `internal/domain/`
2. Implement the repository in `internal/infrastructure/`
3. Write business logic in `internal/application/`
4. Register the route and handler in `internal/interfaces/`

### Hot Reload

Install [air](https://github.com/air-verse/air) then:

```bash
go install github.com/air-verse/air@latest
make watch
```

### Debugging Tips

```bash
make logs                         # Tail all logs
make logs-backend | grep ERROR    # Backend errors only
make status                       # Check service health
curl http://localhost:8090/health # Health check endpoint
```

---

## 📜 License

[Apache License 2.0](LICENSE)

---

<div align="center">
  <sub>Built with ❤️ using Go + React</sub>
</div>