vici-evalution
Enterprise quality-assurance platform for VICIdial call centers: syncs real call logs and recordings from one or many dialer servers, tracks fronter→closer transfers (same-dialer and cross-dialer), and gives QA teams versioned scorecards, secure recording playback, and full admin/audit tooling — all multi-company with strict data isolation.
- Language
- TypeScript
- Stars
- 0
- Last updated
From the README
VICIdial QA Platform
Call-quality review for VICIdial call centres — counts that match the dialer, recordings that appear the moment the dialer has them, and scorecards your reviewers actually finish.
Built for fronter → closer operations: every XFER a fronter makes is tracked to the closer who took it, filed as Transfer → Unclosed → Closed, matched to its recordings, and handed to QA with the lead's full record beside the audio. Multi-company, role-based, audited, and shipped as five Docker containers.
Built and maintained by Abdul Manan.
Contents
- What you get
- How it works
- Install on a server (10 minutes)
- Connect your VICIdial
- Built-in QA forms
- Day-to-day operations
- Remote diagnostics
- Connections (other apps, HRMS, CRM)
- Configuration
- Security
- Troubleshooting
- Project layout & development
What you get
Queues that agree with the dialer
| Queue | What lands here |
|---|---|
| Transfers | every XFER a fronter dispositioned — built from VICIdial's own agent log, so the daily count equals the Agent Status Detail report to the call |
| Unclosed | transfers whose closer leg ended in anything other than a sale |
| Closed | every sale: on the transfer, on a later callback of the same lead, or straight into the closer group — equals the dialer's SALE count |
Counts are per dialer day (the dialer's time zone), with a header switch to show times in the reviewer's own zone. Verified day by day and agent by agent against VICIdial's reports.
Recordings, live
- A call page shows Call in progress → Being prepared on the dialer → playable, refreshing itself every 8 seconds only while something can still change.
- The platform knows how VICIdial names files, so a recording is found the moment the dialer writes it — before the dialer's own list even reports it.
- Stale links heal themselves on play; a Fetch from dialer button forces an immediate re-check.
- 0-second "disposition only" entries are recognised and the real conversation is played instead.
- Every leg shows who hung up (customer / agent / handoff) and every disposition is a colour-coded pill.
QA that fits the workflow
- Three built-in scorecards — TRA (fronter), Unclosed and Closed (closer) — plus a form builder with weights, critical/auto-fail questions, ratings, dropdowns and conditional questions. Every publish is an immutable version; old scores never change.
- Evaluation page: recordings and the lead's full record on the left, the form on the right. Nothing to switch between.
- Daily tasks: managers assign a dialer day's calls, per method, to a reviewer — all of them or a sample.
- Reviewer scoping: limit a reviewer to specific methods/queues and to specific dialer agents.
- Reports: evaluations spreadsheet with one column per question (CSV), QA performance by agent and by reviewer, agent activity straight from the dialer (live + archived days).
Enterprise basics
Multi-company with strict data isolation · roles & permissions (super admin, company admin, QA manager, reviewer) · full audit log · encrypted dialer credentials · 7-day rolling retention that keeps every evaluated call forever · recordings only ever streamed through the authenticated API, never by public URL.
How it works
┌──────────────────────────── your VICIdial ────────────────────────────┐
│ Non-Agent API · read-only MySQL (vicidial_log, closer_log, │
│ (recordings, agent_log, vicidial_list …) · recording web │
│ agents, leads) server (MP3) │
└───────▲──────────────────────────▲─────────────────────────▲──────────┘
│ every 60 s │ │ HEAD/GET
┌──────────────┴──────────────┐ ┌────────┴────────┐ ┌────────┴────────┐
│ worker (BullMQ) │ │ api (Fastify) │◄──────┤ web (nginx) │◄── browser
│ sync · match · recordings │ │ REST + auth + │ │ React app + │
│ retention · repair │ │ recording proxy│ │ /api proxy │
└──────────────┬──────────────┘ └────────┬────────┘ └─────────────────┘
│ │
┌───────▼───────────────────────────▼───────┐ ┌───────────┐
│ PostgreSQL 16 │ │ Redis │
└────────────────────────────────────────────┘ └───────────┘
Sync reads the dialer every minute: calls (outbound + closer-group), the agent log (the source of truth for XFER counts), recordings and the agent roster. Calls are re-read for 12 hours because VICIdial writes a row at call start and rewrites it on disposition. Match links each transfer to its closer leg by lead, phone and timing (auto ≥ 70, flagged 40–69 for a manager to resolve). Recordings are linked to calls by start/end time, verified on the dialer's final MP3, and repaired every minute until the retention window ends.
More depth: docs/ARCHITECTURE.md · docs/VICIDIAL_INTEGRATION.md
Install on a server (10 minutes)
Requirements: a Linux server (Ubuntu 22.04/24.04 or Debian 12), 2 vCPU, 4 GB RAM, 40 GB disk, outbound access to your dialer. Docker is installed for you if missing.
Option A — HTTPS with your own domain (recommended)
Point a DNS A record (e.g. qa.example.com) at the server, open ports 80 and 443, then:
git clone https://github.com/abdulmanan69/vici-evalution.git vici-qa
cd vici-qa
./deploy/install.sh qa.example.comCertificates are issued automatically (Let's Encrypt via Caddy) and renewed forever.
Option B — plain HTTP on a port
git clone https://github.com/abdulmanan69/vici-evalution.git vici-qa
cd vici-qa
./deploy/install.shThe app is on http://<server-ip>:3000 (change WEB_PORT in .env). Use this only inside a private network or behind your own reverse proxy.
The installer writes .env with random secrets, builds and starts the five containers, waits for the API, and prints the super-admin login. Database migrations run automatically at every start. Re-running the installer is safe.
Option C — Coolify
Coolify builds the stack straight from this repository and gives it a domain with HTTPS; nothing is published on host ports.
- + New Resource → Public Repository (or your connected GitHub App), repository
https://github.com/abdulmanan69/vici-evalution.git, branchmain. - Build Pack: Docker Compose. Docker Compose Location:
/docker-compose.coolify.yml. Continue. - Environment Variables tab — the variables from the compose file are listed; set:
APP_ENCRYPTION_KEY— 64 hex characters (openssl rand -hex 32)SUPERADMIN_EMAILandSUPERADMIN_PASSWORD(8+ characters)- leave the rest at their defaults; the Postgres password is generated by Coolify (
SERVICE_PASSWORD_POSTGRES)
- On the
webservice set your domain, e.g.https://qa.example.com(DNS A record pointing at the Coolify server first). Coolify issues and renews the certificate. - Deploy. The first build takes a few minutes (it compiles the API and the web app); every service shows healthy when done. Open the domain and sign in.
Afterwards: a push to main redeploys automatically if you enable the webhook / GitHub App auto-deploy, otherwise press Redeploy. Back up with Coolify's Scheduled Tasks on the postgres service, command pg_dump -U vici_qa vici_qa | gzip > /var/lib/postgresql/data/../backup-$(date +%F).sql.gz, or from the host: docker exec <postgres-container> pg_dump -U vici_qa vici_qa | gzip > vici-qa-$(date +%F).sql.gz.
After the first login
- Change the super-admin password (top-right menu).
- Companies → create your company, then pick it in the scope selector.
- Dialer servers → add your dialer (next section) and press Test connection.
- Dispositions → map your codes (
XFER → Transfer, each sale code →Sale). - Users → invite managers and reviewers; QA team → assign agents and methods.
- Queues fill within a minute; the first sync imports the retention window.
Connect your VICIdial
You need two things from the dialer. Hand DB-ACCESS-REQUEST.md to whoever administers it — it asks for exactly this, nothing more.
1. An API user (user level 9 with API access) — used for recordings, agent lists and lead lookups.
2. A read-only MySQL user on the asterisk database, reachable from this server:
CREATE USER 'qa_readonly'@'<this-server-ip>' IDENTIFIED BY '<strong password>'; GRANT SELECT ON asterisk.* TO 'qa_readonly'@'<this-server-ip>'; FLUSH PRIVILEGES;
The platform only ever runs SELECTs, mostly small time-bounded reads against indexed columns; the load on the dialer is negligible.
In Dialer servers → Add dialer enter the web root (https://your-dialer), the API user, the MySQL host/database/user/password, the recording web server if it differs, and the dialer's time zone (e.g. America/New_York). The time zone matters: VICIdial stores local times, and every count here is per dialer day. The platform also reads the dialer's clock on every sync and warns if the configured zone disagrees.
Press Test connection: both the API and the MySQL checks must pass.
First import. Saving a dialer starts importing its last 7 days (the retention window) straight away — nothing to click. Sync monitor shows it day by day with time left; queues fill in as it goes. If it is interrupted (a deploy, a restart, the dialer dropping the connection) it continues where it stopped; if the dialer cannot be reached it says why in plain words and retries every few minutes. After that the dialer syncs every minute. A new company starts with the stock VICIdial meanings (XFER = transfer, SALE = sale, CALLBK = callback, NI = no sale) — adjust them under Dispositions; changing what counts as a transfer or sale re-reads the last 7 days automatically.
Fronters and closers on different dialers. When one dialer's fronters transfer to closers on another dialer — often a sister company's — those transfers find no closer call on their own dialer and stay in Transfers as "Closer leg not found". A super admin opens Dialer servers → Closer dialers on the fronters' dialer and ticks the closers' dialer. The closer's call is then found there (same phone number, within minutes), and the transfer moves to Unclosed or Closed with that call's recording; transfers already imported are matched again within a few minutes. The fronters' company sees only the closer calls that belong to its own transfers, and the closers' company keeps its own counts exactly as before.
Built-in QA forms
Every company starts with three published scorecards (identical closer forms by design):
| Form | For | Queue | Pass mark |
|---|---|---|---|
| TRA – Transfer Call (Fronter) | fronters | Transfers | 66 % |
| Unclosed – Closer Call | closers | Unclosed | 90 % |
| Closed – Closer Call | closers | Closed | 90 % |
They are ordinary forms: edit them, add questions, re-publish (each publish is a new version; past evaluations keep theirs). If one is archived or lost, QA forms → Load default forms brings back whatever is missing without touching the rest. The same happens automatically at every start and when a company is created. The definitions live in server/src/services/defaultForms.ts.
Day-to-day operations
| Task | Command |
|---|---|
| Update to the latest version | ./deploy/update.sh |
| Back up the database (keeps the newest 14) | ./deploy/backup.sh |
| Nightly backup | crontab -e → 15 2 * * * /opt/vici-qa/deploy/backup.sh >> /var/log/vici-qa-backup.log 2>&1 |
| Restore a backup | ./deploy/restore.sh backups/vici-qa-20261018-021500.sql.gz |
| Status | docker compose ps |
| Logs (API / worker) | docker compose logs -f api · docker compose logs -f worker |
| Restart everything | docker compose restart |
| Full re-sync of a dialer | Dialer servers → Sync (full) |
| Let one person work in several companies | Users & roles → Companies on their row (super admins) |
| Delete a dialer | Dialer servers → Delete (company admins and super admins) |
| Delete a company | Companies → Delete (super admins only) |
People in several companies. A manager or evaluator who works for more than one company keeps one login. A super admin opens Users & roles → Companies on that person's row, picks another company and their role there — they can be a QA manager in one company and a reviewer in another. After signing in, the person chooses the company from the Company switcher in the header; queues, tasks, forms, reports and evaluations all follow it, and the next sign-in opens in the company they used last. In each company the person appears in Users and QA team marked shared, with that company's role, QA-method limits and agent assignments. That company's admins can change their role and limits there or Remove access; their account itself stays with their own company. If their own company is deleted, the account moves to another company they work in.
Deleting. The dialog first counts what goes with the item (calls, recordings, transfers, evaluations, users …) and asks for its exact name. A deleted dialer stops syncing at once and leaves every list and filter; a deleted company's users are signed out and disabled at once. The data is then removed by the worker in small batches, so a big dialer never locks the database, and the row disappears from the admin page when it is done. Names and slugs are free for re-use straight away. QA forms stay when only a dialer is deleted. Every delete is in the audit log.
Retention. Un-reviewed calls, transfers and recordings older than RETENTION_DAYS (default 7) are deleted nightly. Anything with an evaluation, flagged, or closed as a sale is kept forever, with its calls — nothing a reviewer touched is lost, and sales stay on record for the HRMS sales push. Recordings are never copied; they stay on the dialer and stream through the API on demand.
Health. GET /healthz on the API (and through the web container) answers 200 when the database and Redis are reachable; Dialer servers shows the last sync, its duration and any warnings (time-zone mismatch, unmapped dispositions, archive access).
Remote diagnostics
Look inside a running instance from any computer, without SSH and without a login: what is broken, how each dialer is syncing, recent errors, slow pages, the database. It is off until you set a token.
- On your computer, in this repository:
node scripts/ops.mjs init --url https://your-domain. This writes.ops.local(git ignores it) with a new random token. - Copy the
OPS_TOKENvalue from.ops.localto the server — Coolify: the application → Environment Variables →OPS_TOKEN; plain Docker:.env— and redeploy. - Run
node scripts/ops.mjs status.
| Command | Shows |
|---|---|
status |
API, worker, database, Redis, queues and traffic at a glance; a list of problems found (worker down, a dialer not syncing or failing, the 7-day import unfinished, errors, slow or failed requests, restarts); every dialer's last sync and 24-hour counts |
errors [--since 24h] |
warnings and errors from the API and the worker, grouped by message, with stack traces (--list for one line each) |
logs [--since 1h] [--grep text] |
everything the worker reported (each sync, recording check, delete), plus API warnings |
dialers · sync [--dialer name] |
per dialer: last runs, errors, slowest stages, cursors, calls/transfers/recordings in 24 h |
requests |
API timing per minute and per route, and the latest requests slower than 1 s |
companies · queues · db |
per-company counts; background jobs and schedules; database connections, heaviest queries, table sizes |
sql "select …" |
a read-only query |
probe <dialer> |
connects to that dialer's API and database now and reports what answered |
Add --json to any command for the raw answer. Every API and worker warning, error and crash is kept in Redis — the last 2,000 warnings and errors and the last 5,000 lines — with passwords and tokens masked, so restarts do not wipe the trail.
Safety. Nothing here changes data. Every request needs the token (Authorization: Bearer …); a missing or wrong one is refused and noted in the error log. Without OPS_TOKEN the endpoints do not exist. SQL runs as a separate read-only database login that cannot see sessions, password hashes, tokens or the encrypted dialer credentials, one statement at a time, for at most 20 s and a capped number of rows — on users and dialer_servers, name the columns (select * there is refused). OPS_ALLOWED_IPS can limit which addresses may connect. To change the token run init --force and update the server; to switch everything off, empty OPS_TOKEN and redeploy (the read-only login is disabled at the next start).
Connections (other apps, HRMS, CRM)
Admin → Connections (permission Users & roles) lets other apps use QA data. Full reference with curl examples and the webhook signature check: docs/CONNECTIONS.md.
- API keys for a read-only machine API at
/api/v1/ext/…(agents, transfers and sales, completed evaluations, monthly scores, agent activity). Each key has scopes and belongs to one company (super admins can make all-company keys). The key is shown once. - Webhooks: signed POSTs when an evaluation is completed or a sale closes or reopens, retried for about 24 hours.
- Outgoing links: the last run of each push below.
The platform also pushes, every hour:
| To | What | On when |
|---|---|---|
| WaveTech HRMS | QA scores, dialer attendance per shift day, (optionally) closed sales | HRMS_URL and a key (server/src/integrations/hrms) |
| CRM | QA score per agent and month | CRM_URL and CRM_API_KEY (server/src/integrations/crm) |
Configuration
All settings live in .env (template: .env.example). The installer fills the secrets.
| Variable | Default | Meaning |
|---|---|---|
NODE_ENV |
production |
production refuses to start with the placeholder encryption key |
WEB_PORT / WEB_BIND |
3000 / 0.0.0.0 |
where the app listens; WEB_BIND=127.0.0.1 behind the HTTPS proxy |
API_PORT / API_BIND |
8080 / 127.0.0.1 |
the API; the web container reaches it internally |
DOMAIN |
(empty) | enables the HTTPS overlay (docker-compose.https.yml) |
POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD |
— | database credentials (Postgres is bound to localhost only) |
APP_ENCRYPTION_KEY |
— | 32-byte hex key that encrypts dialer credentials at rest |
SESSION_TTL_HOURS |
12 |
login session length |
COOKIE_SECURE |
false |
false = automatic (Secure whenever the page is served over HTTPS); true forces it on |
SUPERADMIN_EMAIL / SUPERADMIN_PASSWORD |
— | bootstrap account, created on first start |
RETENTION_DAYS |
7 |
rolling window for un-reviewed data (0 = keep everything) |
SYNC_POLL_SECONDS |
60 |
how often each dialer syncs |
SYNC_LOOKBACK_MINUTES |
15 |
overlap re-read on every incremental sync |
SYNC_HISTORICAL_DAYS |
30 |
history imported on a full sync (capped by retention) |
RECORDING_CHECK_SECONDS |
60 |
recording repair job cadence |
SYNC_CONCURRENCY |
4 |
dialers synced side by side (each dialer still runs one sync at a time) |
PG_SHARED_BUFFERS / PG_EFFECTIVE_CACHE_SIZE / PG_WORK_MEM |
256MB / 1GB / 16MB |
Postgres memory; on a bigger server set shared buffers to about a quarter of RAM |
PG_LOG_SLOW_MS |
2000 |
Postgres logs statements slower than this |
MATCH_AUTO_THRESHOLD / MATCH_FLAG_THRESHOLD |
70 / 40 |
fronter→closer match scores for auto-link and manual review |
SEED_DEMO |
false |
creates a clearly flagged demo company with synthetic data |
OPS_TOKEN |
(empty) | a random secret of 32+ characters turns on remote diagnostics; empty = off |
OPS_ALLOWED_IPS |
(empty) | optional comma-separated IPs / CIDR ranges allowed to use remote diagnostics |
HRMS_URL / HRMS_API_KEY / HRMS_API_KEYS |
(empty) | WaveTech HRMS link; see the HRMS kit for the other HRMS_* settings |
HRMS_PUSH_ATTENDANCE |
true |
dialer attendance per shift day to the HRMS every hour (needs HRMS_URL); false = off |
CRM_URL / CRM_API_KEY |
(empty) | QA scores to the CRM every hour; empty = off |
Security
- Dialer passwords are encrypted with
APP_ENCRYPTION_KEYand never returned by the API. - Recordings are streamed only through
/api/v1/recordings/:id/stream, behind login, permission and company checks; the dialer's URLs are never exposed to the browser. - Postgres and the API are bound to
127.0.0.1; only the web port (or Caddy's 80/443) faces the network. - Every change — users, roles, forms, dispositions, dialer settings, evaluations, playback — is written to the audit log.
- Sessions are HTTP-only cookies, marked Secure automatically whenever the site is served over HTTPS (
COOKIE_SECURE=trueforces it). - Remote diagnostics are off unless
OPS_TOKENis set, read-only, and their SQL login has no access to sessions, password hashes or dialer credentials.
Troubleshooting
| Symptom | Cause / fix |
|---|---|
port is already allocated on start |
another service owns WEB_PORT; change it in .env and docker compose up -d |
| Test connection fails on MySQL | the dialer's firewall/bind-address or the user's host ('qa_readonly'@'<this-server-ip>') — ask the dialer admin to allow this server's public IP |
| A transfer shows Closer leg not found | the dialer has no closer-side call for it (dropped in queue, outside number, or XFER saved without a transfer) — the page says so after 30 min |
| A recording says Being prepared on the dialer for long | the dialer converts files 1–3 min after hangup; press Fetch from dialer; if it stays, the dialer never produced the file (the dialer's own lead page will show the same) |
| Counts differ from the dialer by a few | check the dialer time zone on the dialer server page and the Dispositions mapping — every XFER code must map to Transfer, every sale code to Sale |
502 right after a restart |
nginx is waiting for the API; it re-resolves within 10 s |
| The site feels slow | Sync monitor shows each sync's seconds per stage — a slow stage is usually the dialer answering slowly. For the database, docker compose exec postgres psql -U vici_qa -d vici_qa -c "select calls, round(mean_exec_time) ms, left(query, 120) from pg_stat_statements order by total_exec_time desc limit 10" lists the heaviest queries |
| Lost the super-admin password | it is in .env as SUPERADMIN_PASSWORD at install time; otherwise reset it from Users with another admin |
Project layout & development
deploy/ install.sh · update.sh · backup.sh · restore.sh · Caddyfile
docker-compose.yml postgres + redis + api + worker + web
docker-compose.https.yml Caddy overlay for automatic HTTPS
docker-compose.coolify.yml the same stack for Coolify (no host ports, proxy-managed domain)
server/
drizzle/ SQL migrations (applied automatically at start)
src/db/ schema, migrator, seed (roles, super admin, default forms)
src/auth/ sessions, permissions, company scoping
src/routes/ REST API (queues, recordings, QA forms, tasks, reports, admin…)
src/services/ default forms · form schema & scoring · live recordings
src/vicidial/ API + MySQL adapters, sync, matcher, recording URL repair
src/integrations/ hrms/ (WaveTech HRMS) · crm/ · connections/ (API keys, machine API, webhooks)
src/worker.ts BullMQ schedulers (sync, recording repair, retention, pushes, webhooks)
web/src/ React app (queues, call pages, evaluation, forms, reports, admin)
docs/ architecture and VICIdial integration notes
scripts/ops.mjs remote diagnostics client (no dependencies; see Remote diagnostics)
Local development:
docker compose up -d postgres redis cd server && npm install && npm run migrate && npm run seed npm run dev # API on :8080 npm run dev:worker # sync worker cd ../web && npm install && npm run dev # :3000, proxies /api to :8080 cd server && npm test # unit tests: matching, scoring, dispositions, time zones, recording URLs
© 2026 Abdul Manan. All rights reserved.