steffenwaldvogel/servicetool

Purpose and Entry Points

ServiceTool is an internal technical-service system for customer, machine, ticket, spare-part, and inbound-email handling, extended with AI-assisted ticket prequalification and parts identification. The maintained runtime is Docker Compose with local Ollama and one.com mail services; README setup notes are explicitly historical. Backend startup and HTTP composition begin at backend/src/server.js; the React SPA begins at frontend/src/main.jsx and routes from frontend/src/App.jsx.

Web Application Boundary

The frontend is a React/Vite operational UI, organized around ticket inbox/detail workflows and master-data views. It calls the backend through a shared API client and maintains session identity in context.

• frontend/src/utils/api.js

• frontend/src/context/AuthContext.jsx

• frontend/src/pages/TicketDetail.jsx

• frontend/src/pages/PosteingangPage.jsx

The backend is a Node/Express API. Route modules form the principal domain boundary—tickets/messages/links, customers/contacts, machines/types/documents, parts, imports, administration, and AI endpoints.

• backend/src/routes/tickets.js

• backend/src/routes/ticketsMessages.js

• backend/src/routes/ai.js

Core Operational Data Model

PostgreSQL is the system of record for ticketing, CRM-like customer data, machines, documents, users/RBAC, notifications, and AI outputs. The base schema is evolved through ordered migrations, including document associations, ticket links, vector search, AI evaluation, and application settings.

• database_schema.sql

• backend/migrations/026_pgvector_rag.sql

• backend/migrations/034_ai_usecases.sql

• backend/migrations/073_vision_ohne_beispielwerte.sql

Database access is centralized through backend/src/config/database.js. DB-enforced audit/history is part of the product boundary described by the schema rather than a frontend concern.

Ticket and Mail Flow

A ticket combines customer, contact, machine, category/status/assignment, messages, attachments, links, and SLA-related state. UI interactions reach ticket routes; ticket-message and link routes handle the communication/thread relationship separately. Incoming mail is parsed, matched to tickets or customers, and unmatched items are exposed for manual triage; outgoing replies use the mail service.

• backend/src/routes/tickets.js

• backend/src/routes/ticketsUnmatched.js

• backend/src/services/emailService.js

• backend/src/services/mailFileParser.js

• backend/src/services/matchingService.js

Attachment ingestion is a security-sensitive boundary and is separated into storage and attachment checks.

• backend/src/services/uploadStore.js

• backend/src/utils/attachmentSecurity.js

AI, Retrieval, and Prequalification Pipeline

The AI subsystem is service-oriented behind the AI API. It processes ticket content and attachments, applies routing/gatekeeper analysis, retrieves indexed knowledge, and produces prequalification, classification, evidence, and benchmarkable outputs. Parts workflows additionally support image and description embeddings plus AI descriptions/evidence.

• backend/src/services/aiService.js

• backend/src/services/vorqualifizierungPipeline.js

• backend/src/services/analyseTorwaechter.js

• backend/src/services/ragService.js

• backend/src/services/ersatzteilKiService.js

The application supports evaluation against gold-standard cases and model/register configuration, with persisted benchmark results.

• backend/src/services/benchmarkService.js

• backend/src/services/modellRegisterService.js

• docs/goldstandard/README.md

A separate Python container provides DINOv2-style image embeddings, while local Ollama is the stated current language-model runtime.

• dino-embed/app.py

• dino-embed/Dockerfile

• docs/DINOv2_SETUP.md

Security, Administration, and Deployment

Session authentication, permission checks, request validation, and maintenance-mode controls wrap API access. RBAC and users are persisted through migrations and exposed through dedicated routes.

• backend/src/middleware/auth.js

• backend/src/middleware/validate.js

• backend/src/middleware/maintenanceMode.js

• backend/src/routes/auth.js

• backend/src/routes/roles.js

Docker Compose orchestrates frontend, backend, database, image-embedding service, and reverse-proxy deployment; Nginx terminates/routes external traffic. Mail and optional Sentry are external integrations.

• docker-compose.yml

• docker-compose.https.yml

• nginx/nginx.conf

• frontend/nginx.docker.conf