# steffenwaldvogel/servicetool architecture

> Architecture diagram of the GitHub repository steffenwaldvogel/servicetool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/steffenwaldvogel/servicetool
- Repository: https://github.com/steffenwaldvogel/servicetool

## Overview

#### 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`

Main entry points: [`backend/src/config/database.js`](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/config/database.js) (Database access), [`backend/src/middleware/auth.js`](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/middleware/auth.js) (API security controls), [`backend/src/services/aiService.js`](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/aiService.js) (AI orchestration), [`frontend/src/main.jsx`](https://github.com/steffenwaldvogel/servicetool/blob/main/frontend/src/main.jsx) (React operations UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web & Edge"]
  node_nginx{{"Nginx reverse proxy<br/>edge proxy<br/>[nginx.conf]"}}
  node_frontend["React operations UI<br/>React/Vite SPA<br/>[main.jsx]"]
  node_api_client["Shared API client<br/>frontend API layer<br/>[api.js]"]
  node_auth_context["Session context<br/>frontend auth state<br/>[AuthContext.jsx]"]
end

subgraph group_api["Backend API"]
  node_server["Express server<br/>Node HTTP composition<br/>[server.js]"]
  node_security["API security controls<br/>auth, validation, maintenance<br/>[auth.js]"]
  node_ticket_routes["Ticket &amp; message routes<br/>Express domain routes<br/>[tickets.js]"]
  node_master_routes["Master-data &amp; admin routes<br/>Express domain routes<br/>[roles.js]"]
  node_ai_routes["AI API routes<br/>Express AI routes<br/>[ai.js]"]
end

subgraph group_data["Data &amp; Mail"]
  node_mail_flow["Mail intake &amp; matching<br/>mail processing services<br/>[emailService.js]"]
  node_attachment_guard["Attachment ingestion<br/>secure file handling<br/>[uploadStore.js]"]
  node_db_access["Database access<br/>PostgreSQL client layer<br/>[database.js]"]
  node_postgres[("PostgreSQL system of record<br/>operational database")]
  node_mail_provider(("one.com mail<br/>external mail service"))
end

subgraph group_ai["AI Pipeline"]
  node_ai_orchestrator["AI orchestration<br/>AI service layer<br/>[aiService.js]"]
  node_prequalification["Prequalification pipeline<br/>routing and gatekeeper analysis"]
  node_rag["Knowledge retrieval<br/>pgvector RAG service<br/>[ragService.js]"]
  node_parts_ai["Parts AI<br/>parts identification service"]
  node_ollama(("Local Ollama<br/>language-model runtime"))
  node_dino["DINO image embeddings<br/>Python embedding container<br/>[app.py]"]
  node_benchmark["AI evaluation &amp; registry<br/>benchmark and model management"]
end

node_nginx -->|"serves SPA"| node_frontend
node_nginx -->|"proxies API"| node_server
node_frontend -->|"uses"| node_api_client
node_frontend -->|"maintains session"| node_auth_context
node_api_client -->|"HTTP requests"| node_server
node_server -->|"applies"| node_security
node_security -->|"authorizes"| node_ticket_routes
node_security -->|"authorizes"| node_master_routes
node_security -->|"authorizes"| node_ai_routes
node_ticket_routes -->|"reads and writes"| node_db_access
node_master_routes -->|"reads and writes"| node_db_access
node_ticket_routes -->|"ticket communications"| node_mail_flow
node_mail_flow -->|"receives and sends"| node_mail_provider
node_mail_flow -->|"ingests attachments"| node_attachment_guard
node_attachment_guard -->|"stores metadata"| node_db_access
node_ai_routes -->|"invokes"| node_ai_orchestrator
node_ai_orchestrator -->|"runs"| node_prequalification
node_prequalification -->|"retrieves evidence"| node_rag
node_ai_orchestrator -->|"identifies parts"| node_parts_ai
node_rag -->|"queries vectors"| node_db_access
node_parts_ai -->|"image embeddings"| node_dino
node_prequalification -->|"LLM inference"| node_ollama
node_parts_ai -->|"LLM inference"| node_ollama
node_ai_orchestrator -->|"evaluates models"| node_benchmark
node_benchmark -->|"persists results"| node_db_access
node_db_access -->|"SQL"| node_postgres

click node_nginx "https://github.com/steffenwaldvogel/servicetool/blob/main/nginx/nginx.conf"
click node_frontend "https://github.com/steffenwaldvogel/servicetool/blob/main/frontend/src/main.jsx"
click node_api_client "https://github.com/steffenwaldvogel/servicetool/blob/main/frontend/src/utils/api.js"
click node_auth_context "https://github.com/steffenwaldvogel/servicetool/blob/main/frontend/src/context/AuthContext.jsx"
click node_server "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/server.js"
click node_security "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/middleware/auth.js"
click node_ticket_routes "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/routes/tickets.js"
click node_master_routes "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/routes/roles.js"
click node_ai_routes "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/routes/ai.js"
click node_mail_flow "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/emailService.js"
click node_attachment_guard "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/uploadStore.js"
click node_db_access "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/config/database.js"
click node_postgres "https://github.com/steffenwaldvogel/servicetool/blob/main/database_schema.sql"
click node_ai_orchestrator "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/aiService.js"
click node_prequalification "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/vorqualifizierungPipeline.js"
click node_rag "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/ragService.js"
click node_parts_ai "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/ersatzteilKiService.js"
click node_dino "https://github.com/steffenwaldvogel/servicetool/blob/main/dino-embed/app.py"
click node_benchmark "https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/benchmarkService.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_nginx,node_frontend,node_api_client,node_auth_context toneBlue
class node_server,node_security,node_ticket_routes,node_master_routes,node_ai_routes toneAmber
class node_mail_flow,node_attachment_guard,node_db_access,node_postgres,node_mail_provider toneMint
class node_ai_orchestrator,node_prequalification,node_rag,node_parts_ai,node_ollama,node_dino,node_benchmark toneRose
```

## Components

### Web & Edge

- [Nginx reverse proxy](https://github.com/steffenwaldvogel/servicetool/blob/main/nginx/nginx.conf): edge proxy · `nginx/nginx.conf`
- [React operations UI](https://github.com/steffenwaldvogel/servicetool/blob/main/frontend/src/main.jsx): React/Vite SPA · Ticket inbox/detail and master-data workflows. · `frontend/src/main.jsx`
- [Shared API client](https://github.com/steffenwaldvogel/servicetool/blob/main/frontend/src/utils/api.js): frontend API layer · `frontend/src/utils/api.js`
- [Session context](https://github.com/steffenwaldvogel/servicetool/blob/main/frontend/src/context/AuthContext.jsx): frontend auth state · `frontend/src/context/AuthContext.jsx`

### Backend API

- [Express server](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/server.js): Node HTTP composition · `backend/src/server.js`
- [API security controls](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/middleware/auth.js): auth, validation, maintenance · Wraps protected API access. · `backend/src/middleware/auth.js`
- [Ticket & message routes](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/routes/tickets.js): Express domain routes · Handles tickets, message threads, links, and unmatched inbox triage. · `backend/src/routes/tickets.js`
- [Master-data & admin routes](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/routes/roles.js): Express domain routes · Serves customers, machines, parts, imports, users, and RBAC. · `backend/src/routes/roles.js`
- [AI API routes](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/routes/ai.js): Express AI routes · `backend/src/routes/ai.js`

### Data & Mail

- [Mail intake & matching](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/emailService.js): mail processing services · Parses inbound mail and matches tickets or customers; sends replies. · `backend/src/services/emailService.js`
- [Attachment ingestion](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/uploadStore.js): secure file handling · Separates storage from attachment security checks. · `backend/src/services/uploadStore.js`
- [Database access](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/config/database.js): PostgreSQL client layer · `backend/src/config/database.js`
- [PostgreSQL system of record](https://github.com/steffenwaldvogel/servicetool/blob/main/database_schema.sql): operational database · Stores operations, RBAC, audit/history, vectors, and AI outputs. · `database_schema.sql`
- **one.com mail**: external mail service

### AI Pipeline

- [AI orchestration](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/aiService.js): AI service layer · Coordinates ticket and attachment analysis behind the AI API. · `backend/src/services/aiService.js`
- [Prequalification pipeline](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/vorqualifizierungPipeline.js): routing and gatekeeper analysis · `backend/src/services/vorqualifizierungPipeline.js`
- [Knowledge retrieval](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/ragService.js): pgvector RAG service · `backend/src/services/ragService.js`
- [Parts AI](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/ersatzteilKiService.js): parts identification service · Produces descriptions, embeddings, and evidence. · `backend/src/services/ersatzteilKiService.js`
- **Local Ollama**: language-model runtime
- [DINO image embeddings](https://github.com/steffenwaldvogel/servicetool/blob/main/dino-embed/app.py): Python embedding container · `dino-embed/app.py`
- [AI evaluation & registry](https://github.com/steffenwaldvogel/servicetool/blob/main/backend/src/services/benchmarkService.js): benchmark and model management · Evaluates gold-standard cases and persists benchmark results. · `backend/src/services/benchmarkService.js`

## Connections

- Nginx reverse proxy → React operations UI: serves SPA
- Nginx reverse proxy → Express server: proxies API
- React operations UI → Shared API client: uses
- React operations UI → Session context: maintains session
- Shared API client → Express server: HTTP requests
- Express server → API security controls: applies
- API security controls → Ticket & message routes: authorizes
- API security controls → Master-data & admin routes: authorizes
- API security controls → AI API routes: authorizes
- Ticket & message routes → Database access: reads and writes
- Master-data & admin routes → Database access: reads and writes
- Ticket & message routes → Mail intake & matching: ticket communications
- Mail intake & matching → one.com mail: receives and sends
- Mail intake & matching → Attachment ingestion: ingests attachments
- Attachment ingestion → Database access: stores metadata
- AI API routes → AI orchestration: invokes
- AI orchestration → Prequalification pipeline: runs
- Prequalification pipeline → Knowledge retrieval: retrieves evidence
- AI orchestration → Parts AI: identifies parts
- Knowledge retrieval → Database access: queries vectors
- Parts AI → DINO image embeddings: image embeddings
- Prequalification pipeline → Local Ollama: LLM inference
- Parts AI → Local Ollama: LLM inference
- AI orchestration → AI evaluation & registry: evaluates models
- AI evaluation & registry → Database access: persists results
- Database access → PostgreSQL system of record: SQL