XteVision Error Tracker | Technical Manual

1. Overview

What is XteVision Error Tracker and who is it for?

1.1 What is XteVision Error Tracker?

XteVision Error Tracker (xtevision-error-tracker v1.2.6) is a vendor-neutral, fully offline, self-hosted full-stack web application for managing error cases, support tickets, project assignments, and personnel logistics. It is designed to be re-branded and run by any company — manufacturing, automation, or service organizations — on their own hardware with no external cloud dependency.

1.2 Key Capabilities

Error Case Management: Track hardware/software errors across industrial equipment (doser systems, applicators, valves, pumps, etc.) with full root-cause analysis, severity tracking, and resolution documentation
Public Ticket Intake: Accept support tickets from external customers via a public-facing form, then internally manage and resolve them
Project & Personnel Logistics: Manage project assignments, track field personnel deployments (trip dates, durations, work descriptions), and link them to projects and error cases
Dual-Server Sync: A LAN-based internal server syncs tickets with a public-facing intake server, with push-back of status updates
AI Knowledge Assistant: Floating chatbot with embedding-based similar-case search and client-side translation
Multi-language UI: data-lang-* attributes for EN/DE/ZH/… translation on the client side
Customizable taxonomy: Component structure, fault types, and personnel lists driven by simple config files

1.3 Target Users

Primary: Any company that installs and supports industrial equipment and needs a centralized system for error cases, tickets, and field logistics
Secondary: Service and maintenance teams that deploy personnel to customer sites and need to link field work to error cases and projects

1.4 White-Labeling

The application ships without any third-party branding. Rename the product, swap the logo, and set your own company name, public server URL, and API key in the configuration. All brand strings live in a small set of places (see Deployment) so a single company can re-brand the platform in minutes.

Re-branding tip: Replace the product name in the HTML title and logo, set your own public server URL, and rotate the JWT secret and public-server API key to your own values before going live.

2. System Architecture

High-level design and communication flow

2.1 High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Browser (Client)                         │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │              Vanilla HTML/CSS/JS (SPA)                     │  │
│  │  ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌──────┐  │  │
│  │  │ Login  │ │ Projects │ │ Cases  │ │Tickets │ │People│  │  │
│  │  └────────┘ └──────────┘ └────────┘ └────────┘ └──────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP/REST API
┌──────────────────────────────┴──────────────────────────────────┐
│                    LAN Server — Express.js (port 5003)            │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────────┐  │
│  │ Auth   │ │Tickets │ │ Cases  │ │People  │ │ AI (translate │  │
│  │        │ │ sync   │ │ CRUD   │ │ CRUD   │ │ + similar)    │  │
│  └────────┘ └────────┘ └────────┘ └────────┘ └──────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                    ┌──────────┴──────────┐
                    │  MySQL 8.0 (mysql2)  │
                    │  error_tracker       │
                    │  8 core tables       │
                    └─────────────────────┘

        ┌──────────────────────────────────────────────────────────┐
        │  Public Server (ticket intake)                           │
        │  HTTPS form → stores tickets → synced by LAN server      │
        └──────────────────────────────────────────────────────────┘

2.2 Communication Flow

Frontend → LAN Server: RESTful HTTP requests to Express.js routes for all CRUD operations and AI helpers
LAN Server → Database: Raw SQL queries via mysql2 — parameterized queries throughout
LAN Server → Public Server: Periodic sync pushes local status updates and fetches new public tickets
Frontend → AI Backend: Translation and similar-case search use a local Ollama instance

2.3 Deployment Model

XteVision Error Tracker is designed for self-hosted, fully offline operation:

Runs as a standalone Node.js server on your own hardware
MySQL on localhost, port 3306, database: error_tracker
All data stays on your local server — no cloud dependencies
The public intake server is optional and configurable to your own domain

3. Technology Stack

Frontend, backend, and infrastructure technologies

Layer	Technology	Purpose
Runtime	Node.js	Server runtime
Framework	Express.js 4.x	Web server + API routes
Database	MySQL 8.0 (via `mysql2`)	Primary data store
Auth	JWT (`jsonwebtoken`) + `bcryptjs`	Password hashing + sessions
File uploads	`multer` (disk storage)	Case & ticket attachments
Translation	Ollama local LLM (`aya-expanse:8b`)	Client-side UI translation
AI search	Ollama (`nomic-embed-text:latest`)	Embeddings + similar-case search
Frontend	Vanilla HTML/CSS/JS + Font Awesome	No-framework single-page app

Note: The AI backend is optional. Translation and similar-case search require a local Ollama instance; the core error-tracking and ticket features work without it.

4. Installation & Setup

Get XteVision Error Tracker running on your server

4.1 Prerequisites

MySQL 8.0 running on the target server
Node.js (for running the Express server)
Modern browser (Chrome/Edge/Firefox)
Local LLM server (optional, for AI Assistant features)

4.2 Install (3 steps)

Install dependencies and start the server. The server serves static files from the project root and exposes APIs on /api/*.

# 1. Install dependencies
npm install

# 2. Start the server (port 5003)
npm start
# or: node server.js

4.3 Access the Application

http://your-server-ip:5003

The LAN server runs on port 5003 by default. Connect from your internal network.

4.4 First-Time Setup

Configure the database: Create the error_tracker database and apply the schema from backup.sql
Set credentials: Edit db.js and routes/auth.js with your own database password, JWT secret, and (if used) public-server API key — move these to a .env file
Configure the taxonomy: Edit components.json and new_parameters/*.txt to match your equipment and fault taxonomy
Open the app: Log in via index.html and start adding projects, cases, and tickets

5. Application Structure

Directory layout and module organization

5.1 Directory Layout

xtevision-error-tracker/
├── server.js                 # Main Express server: routes, auth, uploads, AI, static
├── db.js                     # MySQL connection singleton
├── routes/
│   ├── auth.js               # User registration and login endpoints
│   ├── users.js              # User listing endpoint (for dropdowns)
│   └── tickets.js            # Ticket CRUD, public-server sync, push-to-public
├── index.html                # Main SPA — login, projects, tasks, cases, tickets
├── register.html             # Public user registration page
├── register.js               # Client-side registration logic
├── styles.css                # Full stylesheet — dark/light theme, responsive, animations
├── components.json           # Hierarchical component taxonomy
├── new_parameters/           # Dropdown option lists (integrators, fault types, …)
├── backup.sql                # Full MySQL dump of the database
└── license.txt               # Proprietary license agreement

5.2 Key Files

File	Purpose
server.js	Main Express server — all API routes, auth middleware, file uploads, translation AI, AI knowledge assistant, static file serving
db.js	MySQL connection singleton
routes/auth.js	User registration and login endpoints
routes/users.js	User listing endpoint (for dropdowns)
routes/tickets.js	Ticket CRUD, public-server sync, push-to-public logic
index.html	Main SPA — login, projects, tasks, cases, tickets tabs
register.html	Public user registration page
register.js	Client-side registration logic
styles.css	Full stylesheet — dark/light theme, responsive layout, animations
components.json	Hierarchical component taxonomy (RAM, IFC system, Doser system, Applicator, etc.)
*new_parameters/.txt**	Dropdown option lists (integrators, fault types, sub-types, personnel, etc.)
backup.sql	Full MySQL dump of the database
license.txt	Proprietary license agreement

6. Database Schema

Key tables and their purpose

6.1 Core Tables

Table	Purpose	Key Fields
users	Auth users	`id, username, email, password_hash, full_name, role`
tasks	Projects/tasks	`id, pm_number, pm_name, integrator, capture_date, start_at, finished_at`
projects	Higher-level project groupings	`id, project_number, project_name`
error_cases	Detailed error reports (~40 fields)	`case_id, system info, error description, root cause, severity, resolution, lessons learned`
case_attachments	File attachments linked to error cases	`case_id, file_path, original_filename, file_type`
tickets	Support tickets	`id, public_id, customer_name, subject, description, source, status, linked_case_id, sync_required`
ticket_attachments	File attachments linked to tickets
personell_arrangement	Personnel deployment records	`project_number, integrator, personnel, trip_start_date, trip_return_date, duration_days, work_description, show_flag`

error_cases is the central table with ~40 fields covering system information, error description, root cause, severity, resolution, and lessons learned — the backbone of your knowledge base.

7. Core Features

Key platform capabilities

Error Case Management

Track hardware/software errors across industrial equipment with ~40 fields, root-cause analysis, severity tracking, resolution documentation, and lessons learned.

Public Ticket Intake

Accept support tickets from external customers via a public form, then manage, link, and resolve them internally with sync to your public server.

Personnel Logistics

Manage project assignments and field deployments — trip dates, durations, work descriptions — linked to projects and error cases.

Dual-Server Sync

Periodic sync pushes local status updates and imports new public tickets, with attachments downloaded and stored locally.

AI Similar-Case Search

Generates embeddings for a ticket's subject/description and finds top-N similar error cases via cosine similarity.

Client Translation

Client-side translate links trigger a local LLM; supports multiple target languages via data-lang-* attributes.

File Attachments

Case and ticket attachments stored with timestamped filenames via multer, served through two static mounts.

Custom Taxonomy

Equipment structure, fault types, and personnel lists are driven by simple config files (components.json, new_parameters/*.txt).

Themeable UI

Full dark/light theme support with responsive layout and animations, all in a single stylesheet.

8. Module Details

In-depth feature documentation

8.1 Authentication & Security

JWT-based authentication with the following mechanisms:

Token expiry: 8-hour JWT lifetime
Password hashing: bcrypt with cost factor 10
Auth middleware: authenticateToken checks the Authorization: Bearer <token> header
SQL injection prevention: Parameterized queries throughout; sort fields use a whitelist approach

Security hardening: The JWT secret, database password, and public-server API key should be externalized to a .env file rather than left hardcoded in routes/auth.js and db.js.

8.2 File Uploads

Case attachments stored in uploads/case_<id>/ with timestamped filenames
Ticket attachments stored in uploads/ (synced from public server) and web_tickets/uploads/ (public form uploads)
Two express.static mounts for /uploads cover both directories

8.3 Translation Feature

Client-side translate links trigger POST /api/translate → Ollama aya-expanse:8b
Supported target languages: de, en, ru, es, jp, fr, th, vt

8.4 AI Knowledge Assistant

POST /api/ai/find-similar-cases — generates embeddings for a ticket's subject/description using nomic-embed-text, then finds top-N similar error cases via cosine similarity
Embeddings are stored in the database for reuse

8.5 Public Server Sync

routes/tickets.js exports syncTicketsFromPublicServer() which:

Pushes local ticket updates (status changes with sync_required = 1) to the public server
Fetches all public tickets and imports new ones locally (by matching customer_name + subject + created_at)
Downloads and stores attachments from the public server

Status updates to tickets automatically set sync_required = 1 for pushback.

8.6 Dual Server Communication

Public server URL is configurable to your own domain (default placeholder: https://error-tracker.example.com)
Push API key is configurable — rotate to your own secret before going live

9. AI Integration

Local LLM–powered knowledge assistant

9.1 Local LLM Backend

All AI features run against a local Ollama instance, keeping customer data fully on-premise:

Translation: aya-expanse:8b for client-side UI translation
Embeddings: nomic-embed-text:latest for similar-case search
Optional: Core tracking/ticket features work without the AI backend

9.2 Similar-Case Search

Feature	Description
Endpoint	`POST /api/ai/find-similar-cases`
Embedding model	`nomic-embed-text:latest`
Matching	Top-N similar error cases via cosine similarity
Storage	Embeddings stored in the database for reuse

Example: Paste a new ticket subject/description and the assistant returns the closest matching error cases from your knowledge base.

10. Deployment

Run and manage the platform on your server

10.1 Requirements

Node.js (for running the Express server)
MySQL 8.0 (via mysql2)
Local LLM server (optional, for AI Assistant features)

10.2 Start the App

# Install dependencies
npm install

# Start the server (port 5003)
npm start
# or: node server.js

10.3 Configuration

Setting	Location	Description
Database password	`db.js`	MySQL connection credentials
JWT secret	`routes/auth.js`	Session signing secret — rotate to your own value
Public server URL	`routes/tickets.js`	Your own intake domain (replace placeholder)
Public push API key	`routes/tickets.js`	Rotate to your own secret before going live
Product name / logo	`index.html`	White-label branding — set your own company name

Re-branding checklist: Set your own product name and logo in index.html, replace the public server URL with your own domain, and rotate the JWT secret and public-server API key. Then move all secrets into a .env file.

10.4 Upgrading to a New Version

# 1. Stop the server
npm stop

# 2. Back up your data and config
cp backup.sql /tmp/et-backup.sql
cp db.js /tmp/et-db.bak

# 3. Install the new version, then restore config
npm install

# 4. Restart
npm start

Always back up backup.sql (your data) and db.js / routes/auth.js (your credentials) before upgrading.

11. Changelog

Version history and release notes

v1.2.6 — Current

Error Case Management: ~40-field error reports with root-cause analysis, severity tracking, resolution, and lessons learned
Public Ticket Intake: Public form with dual-server sync and push-back of status updates
Personnel Logistics: Deployment tracking linked to projects and error cases
AI Knowledge Assistant: Embedding-based similar-case search and client-side translation
File Attachments: Case and ticket attachments with timestamped filenames
Multi-language UI: EN/DE/ZH/… translation via data-lang-* attributes
Custom Taxonomy: Equipment structure and fault types driven by config files
White-Label Ready: No third-party branding; rename and re-brand in minutes

12. Troubleshooting

Common issues and solutions

12.1 Server Won't Start

Issue: Port already in use
Solution: Change the port or kill the existing process, then restart.

12.2 Database Connection Failed

Issue: "Connection refused" to MySQL
Solution: Verify MySQL is running. Check db.js credentials. Ensure the error_tracker database exists. Re-apply the schema from backup.sql.

12.3 Data Not Visible After Login

Issue: Pages show empty after login
Solution: Verify the user has the correct role and that the schema has been applied. Check the database connection in db.js.

12.4 AI Chat Not Responding

Issue: "Connection refused" or no response from AI
Solution: Ensure the local Ollama server is running and the model (aya-expanse:8b / nomic-embed-text:latest) is pulled. AI features are optional — the core tracking works without it.

12.5 Sync Not Working

Issue: Public tickets not imported or status not pushed
Solution: Verify the public server URL and API key in routes/tickets.js. Check network connectivity and that sync_required = 1 is set on status updates.

12.6 Attachments Not Showing

Issue: Files missing after upload
Solution: Verify the uploads/ directory exists and has write permissions. Check the upload API route and that the multer middleware is configured.

Error TrackingSupport Platform

1. Overview

1.1 What is XteVision Error Tracker?

1.2 Key Capabilities

1.3 Target Users

1.4 White-Labeling

2. System Architecture

2.1 High-Level Architecture

2.2 Communication Flow

2.3 Deployment Model

3. Technology Stack

4. Installation & Setup

4.1 Prerequisites

4.2 Install (3 steps)

4.3 Access the Application

4.4 First-Time Setup

5. Application Structure

5.1 Directory Layout

5.2 Key Files

6. Database Schema

6.1 Core Tables

7. Core Features

Error Case Management

Public Ticket Intake

Personnel Logistics

Dual-Server Sync

AI Similar-Case Search

Client Translation

File Attachments

Custom Taxonomy

Themeable UI

8. Module Details

8.1 Authentication & Security

8.2 File Uploads

8.3 Translation Feature

8.4 AI Knowledge Assistant

8.5 Public Server Sync

8.6 Dual Server Communication

9. AI Integration

9.1 Local LLM Backend

9.2 Similar-Case Search

10. Deployment

10.1 Requirements

10.2 Start the App

10.3 Configuration

10.4 Upgrading to a New Version

11. Changelog

v1.2.6 — Current

12. Troubleshooting

12.1 Server Won't Start

12.2 Database Connection Failed

12.3 Data Not Visible After Login

12.4 AI Chat Not Responding

12.5 Sync Not Working

12.6 Attachments Not Showing

Error Tracking
Support Platform