Getting Started

Get ServiFlow running locally in under five minutes.

Prerequisites

• Node.js 14 or later
• MySQL 8.x running locally (or a remote instance)

Install & Run

# Install dependencies
npm install

# Create databases & seed data
npm run setup-db

# Start the server
npm start

Open http://localhost:3000 in your browser.

Default Credentials

When logging in as a tenant user, use the tenant code apoyar.

Environment Variables

# .env file
MASTER_DB_HOST=localhost
MASTER_DB_PORT=3306
MASTER_DB_USER=root
MASTER_DB_PASSWORD=
MASTER_DB_NAME=a1_master
PORT=3000

# Email (Gmail SMTP)
SMTP_EMAIL=your-email@gmail.com
SMTP_PASSWORD=your-app-password

Architecture

Multi-Tenant Database

ServiFlow uses a database-per-tenant isolation model:

• Master DB (a1_master) — tenants, master_users, plans, subscriptions, billing
• Tenant DBs (a1_tenant_{code}) — users, tickets, cmdb_items, sla_definitions, etc.

┌─────────────┐   ┌────────────────┐   ┌────────────────┐
│  a1_master  │   │ a1_tenant_     │   │ a1_tenant_     │
│             │   │ apoyar         │   │ bleckmann      │
│ master_users│   │ users          │   │ users          │
│ tenants     │   │ tickets        │   │ tickets        │
│ plans       │   │ cmdb_items     │   │ cmdb_items     │
└─────────────┘   └────────────────┘   └────────────────┘
        │                  │                    │
        └──────────────────┼────────────────────┘
                           │
                   ┌───────────────┐
                   │  Express API  │
                   │  + SPA Front  │
                   └───────────────┘

Key Files

Technology Stack

• Backend: Node.js + Express
• Database: MySQL (mysql2)
• Auth: JWT (jsonwebtoken) + bcrypt
• Security: Helmet, CORS, rate limiting
• Email: Nodemailer (Gmail SMTP)
• Frontend: Single-page HTML + vanilla JS

Security

• JWT token authentication on every API call
• bcrypt password hashing (10 rounds)
• Strict tenant isolation — queries always scoped to tenant DB
• Role-based access control (Master Admin, Admin, Expert, Customer)
• Helmet.js security headers
• CORS protection

Feature Overview

Core Capabilities

• Multi-Tenant SaaS — database-per-tenant isolation, self-service signup
• Ticket Management — create, assign, track, resolve with full activity logging
• SLA Tracking — real-time countdowns, breach notifications, pause/resume
• CMDB — configuration item management, asset viewer, custom fields
• Knowledge Base — article creation, categorisation, search
• AI Insights — sentiment analysis, trend detection, root-cause identification
• Email Processing — inbound email creates/updates tickets with threading
• Ticket Processing Rules — automated actions on matching tickets
• Customer Management — CRUD with domain-based email matching
• Analytics Dashboard — charts, SLA compliance, resolution trends
• Housekeeping — configurable data retention and ticket pruning

User Roles

Email System

• Nodemailer + Gmail SMTP integration
• Notifications for ticket creation, status changes, and resolution
• Inbound email processing with reply threading (header → subject token → URL → domain match)
• HTML email templates

Ticket Management

Ticket Workflow

Tickets progress through the following statuses:

Open → In Progress → Pending → Resolved → Closed

Status Descriptions

SLA Tracking

Each ticket can have an SLA definition applied that tracks:

• Response time — time until first response (first_responded_at)
• Resolution time — time until ticket is resolved
• Real-time countdown timers in the UI
• Colour-coded risk indicators (OK → Warning → Danger)
• Email notifications at near-breach, breach, and past-breach thresholds
• Pause and resume SLA timers (e.g. waiting for customer)

Activity Logging

Every ticket action is recorded in the ticket_activity table:

Demo Scenarios

1. Admin: View all tickets, assign to experts, manage SLA definitions
2. Expert: Work assigned tickets, update status, use completion modal
3. Customer: Raise requests, track status, view CMDB assets

Customer Management

CRUD Operations

Company Domain Matching

The company_domain field is critical for the email-to-ticket system:

1. Customer sends email from john@acme.com
2. System extracts domain: acme.com
3. Looks up domain in customers table
4. Creates ticket for that customer (or creates a new customer user if none exists)

Database Schema

Security

• Domain format validation (regex: [a-z0-9][a-z0-9-]*\.[a-z]{2,})
• Random 10-character password generated on creation (bcrypt hashed)
• Soft delete preserves data; cannot delete customers with active tickets
• Rate limiting: 30 write operations per 15 minutes

AI Insights

Automatic Analysis

Every incoming ticket is analysed for:

• Sentiment: urgent, negative, neutral, positive
• Category: Infrastructure, Database, Storage, Network, Performance
• Root Cause: system, hardware, software, network, database, resource
• Impact Level: low, medium, high, critical
• Key Phrases & Technical Terms
• Confidence Score (0–100%)
• Estimated Resolution Time

Trend Detection

Automatically detects:

• Volume Spikes — unusual increases in ticket volume
• Recurring Issues — same category appearing repeatedly
• SLA Risks — tickets approaching deadline
• Urgent Backlogs — critical tickets not being addressed

Dashboard Actions

API Endpoints

Database Tables

• ai_email_analysis — per-ticket analysis results
• ai_insights — detected trends and alerts
• ai_category_mappings — pattern learning
• ai_system_metrics — performance tracking

Ticket Processing Rules

Create automated rules that match tickets by search criteria and perform actions.

Rule Configuration

Action Types

Examples

Auto-assign infrastructure alerts

{
  "rule_name": "Auto-assign Infrastructure",
  "search_in": "title",
  "search_text": "Infrastructure Monitoring",
  "action_type": "assign_to_expert",
  "action_params": { "expert_id": 1, "expert_name": "Infrastructure Team" }
}

Escalate urgent tickets

{
  "rule_name": "Escalate Critical",
  "search_in": "title",
  "search_text": "URGENT",
  "case_sensitive": true,
  "action_type": "set_priority",
  "action_params": { "priority": "critical" }
}

API Endpoints

All prefixed with /api/ticket-rules/:tenantId.

API Reference

All endpoints require a Bearer token in the Authorization header unless noted.

Authentication

Tickets

Master Admin

Customers

Analytics & AI

Admin Settings

Health & Status

Troubleshooting

Server Hangs on Login

Usually caused by MySQL connection pool exhaustion.

# Kill stale node processes
pkill -f "node.*server"
lsof -ti:3000 | xargs kill -9

# Clean stale MySQL connections
mysql -u root -e "SELECT CONCAT('KILL ', id, ';') \
  FROM information_schema.processlist \
  WHERE user='root' AND command='Sleep' AND time > 60;" -N | mysql -u root

# Restart
npm start

MySQL Connection Issues

# Check MySQL service
sudo systemctl start mysql
sudo systemctl enable mysql

# Ensure root has privileges
mysql -u root -p
GRANT ALL PRIVILEGES ON *.* TO 'root'@'localhost';
FLUSH PRIVILEGES;

Port Conflicts

# Use a different port
PORT=3001 npm start

Railway Deployment Not Updating

Changes must be committed to git before railway up. Railway deploys from git, not local files.

git add .
git commit -m "Your message"
railway up --detach

Customer Domain Issues

Ticket Rules Not Matching

1. Verify search text is correct
2. Try with case-sensitive disabled
3. Check if searching in the correct field (title / body / both)
4. Use the Test button to preview matches before enabling

AI Insights Not Loading

1. Check browser console for API errors
2. Verify authentication token is valid (re-login if expired)
3. Ensure the ai_email_analysis table exists in the tenant database
4. Try clicking Refresh or Detect Trends to regenerate data

Adding Columns to Existing Tenant DBs

When adding new columns, update all tenant databases:

# Get Railway MySQL password
railway variables | grep MYSQLPASSWORD

# Run migration on each tenant DB
mysql -h tramway.proxy.rlwy.net -P 19355 -u root -p{PASSWORD} -e "
ALTER TABLE a1_tenant_{code}.tickets ADD COLUMN new_col TYPE;"