21 KiB
Feuerwehr Schadensmeldung
Fault management for technical equipment of a German fire brigade. Members report defects on devices (radios, breathing apparatus, vehicles, ...), the responsible unit tracks and resolves them, and a public dashboard in the equipment room shows everything that is currently broken.
The application consists of:
- a Go backend with Gin, Gorm and swaggo API docs (backend)
- a React + TypeScript frontend built with Vite (frontend)
The user interface is German; code and documentation are English.
Features
- OIDC login with automatic user creation. Roles are derived from OIDC groups/emails on every login, the identity provider is the single source of truth for role management.
- Faults with title, description, device, location, priority and status
(
open,in_progress,resolved), filtering, full-text search and history. - Assignees: while a fault is in progress, users (or yourself via "Mir zuweisen") can be assigned to it in the edit dialog. They stay visible on the resolved fault and are removed when it is set back to open. Only users who logged in at least once can be assigned. Users assigned by someone else are notified, see Notifications below.
- Updates: while a fault is in progress, users post short progress messages ("Ersatzteil bestellt",
"Wartet auf Werkstatt") in a chat-like thread in the edit and detail dialogs
(
GET/POST /api/v1/faults/{id}/updates). The thread stays readable after the fault is resolved. - Responsibilities ("Verantwortlichkeiten", called fault types in the API), seeded with
IUK,GerätewartandAtemschutz. Each can be restricted to OIDC groups, see below. - Locations (vehicles, rooms, ...) selectable from a dropdown, managed in the admin UI.
- Reparaturschein: an A4 PDF for an external repair service with the device (name,
manufacturer, type, serial and inventory number, barcode and, from MP-Feuer, production year and
date in service), the fault details, a free text and fields for the repair service to fill in.
Created from an open fault and opened in a new browser tab
(
POST /api/v1/faults/{id}/repair-order). - Public dashboards (kiosk mode) registered once by an admin with a short registration code: show all open faults, report new faults, resolve faults and browse the history without a personal login.
- AI assistant and summaries via any OpenAI compatible API such as Ollama or OpenWebUI (optional), see AI integration below.
- Per user default filter for the overview (fault type, location, priority, status), set in the settings.
- Personal API tokens for integrations, Swagger UI at
/api/docs/index.html. - Light/dark mode, responsive layout, installable PWA: starts offline from the cached app shell, shortcuts for "Neue Meldung" and "Historie", and a notice when a new version is available (public dashboards update automatically).
- URL routing: every view has its own address, filters and page are kept in the query string,
so links can be shared and the back button works:
Path Content /open faults, e.g. /?prioritaet=high&standort=3&seite=2/meldungen/neunew fault dialog, ?barcode=ag002prefills the barcode (e.g. for QR codes on devices)/meldungen/<id>a single fault, linked from the notification mails /historieresolved faults, same filter parameters /assistentAI assistant (only if the AI integration is enabled) /einstellungensettings /admin/<tab>verantwortlichkeiten,standorte,dashboards,benutzer,branding,ki
Roles
| Role | Granted by | Permissions |
|---|---|---|
admin |
OIDC_ADMIN_GROUPS or OIDC_ADMIN_EMAILS |
everything, incl. fault types, locations, dashboards, users, branding, deleting faults |
user |
any other authenticated user (optionally restricted by OIDC_USER_GROUPS) |
report, edit, resolve and reopen faults |
The role is re-evaluated on every login, so removing a user from the admin group in the
identity provider downgrades them on their next login. There is no manual role assignment in
the application. If OIDC_USER_GROUPS is set, users that are neither in one of these groups
nor admins are rejected at login.
Responsibilities and OIDC groups
Admins can assign OIDC groups to a responsibility under Admin → Verantwortlichkeiten.
- No groups: the history of this responsibility is visible to everyone, no mails are sent.
- With groups: resolved faults of this responsibility are only visible to members of one of the groups and to admins. Open faults stay visible to everyone.
- Notification: when a new fault is reported for a responsibility with groups, every member is notified (except the reporter), see Notifications below.
Group memberships are taken from the OIDC claims and stored on every login. Users who never logged in are unknown to the application and therefore receive no mails; a membership change in the identity provider takes effect on the user's next login.
Public dashboards show the history of unrestricted responsibilities. The history of restricted ones has to be enabled per dashboard under Admin → Dashboards → Bearbeiten.
Notifications
Users are notified about new faults of their responsibilities and about faults assigned to them by someone else. Under Einstellungen → Benachrichtigungen every user chooses per notification type which transports to use; all are enabled by default.
- E-Mail requires the
SMTP_*settings. - Push (Web Push) works without external services. The user enables it per device under
Push-Geräte; clicking a notification opens the fault. On iPhone/iPad the app has to be
added to the home screen first. Browsers only offer push on HTTPS (or
localhost) and the service worker is only active in production builds, so test it withyarn build && yarn previewinstead ofyarn dev. A VAPID key pair is generated on first use and stored in the database, so all replicas share it. SetVAPID_PUBLIC_KEY/VAPID_PRIVATE_KEYto provide your own; changing the keys invalidates all existing push subscriptions.
MP-Feuer hand-over
If a MP-Feuer database is configured (MPFEUER_DB_*), logged-in users can tick
"An MP-Feuer übergeben" when finishing a fault. The fault's barcode is looked up in
<PREFIX>_STAMM.<PREFIX>_BARCODE_NR and <PREFIX>_BARCODE_NR2 of all prefixes
(GAS, GEL, GFU, GHR, GMP, GSL, GSO, KLD); exactly one device must match. The dialog shows the
device before the user confirms. A new row is then inserted into <PREFIX>_MANGEL:
| Column | Value |
|---|---|
_ID |
new GUID of the defect |
_INDEX |
device GUID (<PREFIX>_STAMM.<PREFIX>_ID) |
_MANGEL_ZEIT, _CREATED_TS |
creation time of the fault |
_MANGEL_ERFASSER |
name of the reporter |
_MANGEL_ERFASSER_HDZ, _CREATED_HDZ |
MPFEUER_HANDZEICHEN (default SM) |
_MANGEL_ERLAEUTERUNG |
fault title |
_MANGEL_LANG |
description (MP-Feuer limits it to 50 characters) |
_MANGEL_PRIORITAET |
1 for priority "Hoch" |
_INFOTEXT |
details without an own column (report number, low/medium priority, resolver name, Maßnahme); reporter and description only when they do not fit their column |
_UPDATED_TS |
time the fault was finished |
_UPDATED_HDZ, _MANGEL_HDZ |
the user's "MP-Feuer Handzeichen" (settings), falls back to MPFEUER_HANDZEICHEN |
_MANGEL_OK |
1, the defect is recorded as done |
_MANGEL_STATUS |
Erledigt |
_MANGEL_TERMIN |
date the fault was finished |
All other columns keep their defaults. MP-Feuer's timestamp triggers would
overwrite the CREATED_/UPDATED_ columns with the current MP-Feuer user, so the insert runs in
MP-Feuer's transfer mode (SYS_SET_TRANSFER_MODE) for its own session. Texts are truncated to the
column lengths. The hand-over happens before the fault is resolved: if it fails, the fault stays
open and the error is shown. The created reference is stored on the fault and shown in the history.
When a barcode is entered or scanned while reporting a fault (app and public dashboard), it is looked up in MP-Feuer and empty fields are prefilled: Gerät from the device name (or manufacturer and type), number and call sign, and Standort from the mapping below.
Standort mapping
Under Admin → Standorte → MP-Feuer zuordnen admins search MP-Feuer and map entities to a Standort. Each entity can only be mapped to one Standort:
| Kind | Source in MP-Feuer | Matches a device when |
|---|---|---|
| Fahrzeug / Zuteilung | vehicles (FZG_STAMM) and assignment targets used by devices |
_ZUTEIL_KEY equals the entity GUID |
| Standort-Text | distinct _STANDORT values of devices and vehicles |
_STANDORT equals the text (case-insensitive) |
| Abteilung | ABT_STAMM |
_ABT_INDEX equals the department GUID |
The most specific mapping wins (Zuteilung, then Standort-Text, then Abteilung); inactive Standorte are ignored. Without a mapping, a Standort whose name equals the assignment name or location text is used.
To verify a configuration without writing anything, run the dry run, which inserts and rolls back:
cd backend && MPFEUER_DRYRUN=1 go test ./internal/mpfeuer/ -run DryRun -v
Public dashboards
- An admin opens Admin → Dashboards and creates a dashboard (e.g. "Tablet Fahrzeughalle").
- A short registration code (e.g.
K7QF-2M9X) is shown once. It is valid for 24 hours and can be redeemed exactly once. - On the dashboard device, open
/dashboardand enter the code (case and dash are ignored). The device receives the real secret (db_...) in exchange, which is stored in the browser's local storage and sent asX-Dashboard-Tokenheader. Wrong codes are rate limited. - The dashboard refreshes automatically every 30 seconds. People reporting or resolving a fault on the dashboard enter their name, which is stored with the fault.
Admins can disable a dashboard, rotate its secret or delete it; the device loses access immediately. Only a SHA-256 hash of the secret is stored in the database.
MCP server
The user features are available to AI assistants as a Model Context Protocol
server (streamable HTTP, stateless) at /api/v1/mcp. It is enabled whenever OIDC is configured.
- Authentication: the backend is its own OAuth 2.1 authorization server for MCP clients (dynamic
client registration, authorization code grant with PKCE S256, refresh tokens) and signs the user in at
the configured OpenID provider. MCP clients need no client at the identity provider; the existing
OIDC_REDIRECT_URLcallback is reused, so nothing else has to be registered there.- An unauthenticated request gets
401with a pointer to/api/v1/mcp-metadata(RFC 9728), which names this server (/api/v1/oauth) as authorization server (RFC 8414 metadata is served below/api/v1/oauth/.well-known/and at/.well-known/; the Helm ingress forwards these viaingress.wellKnownPaths). - The client registers itself at
/api/v1/oauth/registerand sends the user to/api/v1/oauth/authorize. The user first confirms the client, then signs in at the OIDC provider. Role and groups are mapped exactly like for a browser login (OIDC_ADMIN_GROUPS,OIDC_USER_GROUPS). - The client exchanges the code at
/api/v1/oauth/tokenfor an access token (default 1 hour) and a refresh token (default 30 days), both issued by this server and stored hashed in the database. Deleting a user revokes their tokens.
- An unauthenticated request gets
- Configuration: set
APP_URLso the metadata contains the public URL. Optional lifetimes:MCP_OAUTH_AUTH_CODE_TTL_SECONDS(300),MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS(3600),MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS(2592000). - Tools:
get_me,get_my_groups,get_catalog,list_users,get_fault_summary,list_open_faults,list_fault_history,get_fault,list_fault_updates,add_fault_update,report_fault,update_fault,resolve_fault,reopen_fault,lookup_mp_feuer_device,create_repair_order(PDF),update_preferences. Admin features (deleting faults, administration) are not exposed. - Tools call the regular REST API in-process as the signed-in user, so visibility rules, notifications and the MP-Feuer hand-over behave exactly like in the web app. MCP tokens are not accepted by the REST API itself.
AI integration
The application can use any OpenAI compatible API; /chat/completions and /models are appended to the
configured API URL. An admin configures it under Admin → KI: API URL, optional API key and model.
"Verbindung testen & Modelle laden" lists the available models. Examples for the API URL:
| Server | API URL | API key |
|---|---|---|
| Ollama | http://ollama:11434/v1 |
not needed |
| OpenWebUI | https://openwebui.example.org/api |
Settings → Account |
| OpenAI | https://api.openai.com/v1 |
required |
The settings are stored in the database; the API key is never sent back to the browser. Each feature below can
be switched off on its own. "Denkmodus deaktivieren" sends "reasoning_effort": "none" (understood by Ollama's
/v1 API), "think": false and adds /no_think (Qwen3) to the system prompt, which makes reasoning models like
Gemma 4 or Qwen3 answer much faster; leading thinking blocks (<think>…</think>, Gemma 4's <|channel>thought…<channel|>) are always removed
from answers. Strict
servers like OpenAI may reject these parameters, so only enable it for Ollama or OpenWebUI. When enabled:
- KI-Assistent (
/assistent,POST /api/v1/ai/chat): a chat about the faults. The model gets the read-only tools of the MCP server (get_catalog,list_open_faults,list_fault_history,get_fault, ...), which call the REST API in-process as the signed-in user, so it sees exactly what the user may see. It cannot report, change or resolve faults; tool calls for anything else are refused. The model should support function calling. The conversation is kept in the browser tab only. - KI-Zusammenfassung: a situation report of all open faults on the overview (
POST /api/v1/ai/summary) and a summary of a single fault in its dialog (POST /api/v1/ai/faults/{id}/summary). Summaries are only created on request. - Abschlussvermerk: when closing a fault, "Mit KI aus den Updates erstellen" drafts the note "Was wurde
gemacht?" from the fault and its updates; text already typed is used as draft
(
POST /api/v1/ai/faults/{id}/resolution-note). The suggestion stays editable and nothing is saved until the user resolves the fault.
Answers are streamed to the browser as server-sent events (Accept: text/event-stream, see
backend/api/airoutes), so text appears while the model writes; without that header the endpoints answer with
JSON. Tool results are compacted (no colors, empty fields or seconds) and the system prompt only contains the date,
so local servers like Ollama can reuse their prompt cache between requests. A reverse proxy must not buffer these
responses; the backend sends X-Accel-Buffering: no, which nginx and ingress-nginx respect.
Fault data (titles, descriptions, names of reporters and assignees) is sent to the configured AI server (and, for OpenWebUI, to the model provider configured there).
Backend structure
backend/
├── main.go entry point and swagger annotations
├── database/ gorm connection, models, default seed data, legacy migrations
├── docs/ generated swagger docs (swag init --parseInternal)
├── internal/
│ ├── auth/ OIDC (go-oidc + PKCE), sessions, role mapping, middleware
│ ├── faults/ fault listing, creation, resolution (shared by user and dashboard API)
│ ├── dto/ API request/response types
│ ├── repairorder/ "Reparaturschein" PDF (go-pdf/fpdf)
│ ├── ai/ OpenAI compatible client (Ollama, OpenWebUI, ...) and settings
│ └── appsettings/ branding
└── api/
├── webserver.go, routes.go
├── apiutil/ shared handler helpers
├── authroutes/ /api/v1/auth/*
├── catalogroutes/ /api/v1/catalog (locations and fault types)
├── faultroutes/ /api/v1/faults/*
├── meroutes/ /api/v1/me/* (API tokens)
├── adminroutes/ /api/v1/admin/*
├── mcproutes/ /api/v1/mcp (MCP server, tools call the REST API in-process)
├── airoutes/ /api/v1/ai/* (chat and summaries using the read-only MCP tools)
├── dashboardroutes/ /api/v1/dashboard/* (public dashboards)
├── generalroutes/ health checks
└── staticroutes/ serves frontend/dist if present
Sessions are stored server side (only the SHA-256 hash of the cookie value is persisted), as is the short-lived OIDC login state, so multiple backend replicas work without sticky sessions.
Requirements
- Go
1.27 - Node.js
22+ - Yarn
1.x
Local setup
cp backend/.env.example backend/.env # then adjust the OIDC settings
cd backend && go run . # http://localhost:8080
cd frontend && yarn install && yarn dev # http://localhost:5173
The Vite dev server proxies /api/* to http://localhost:8080 (override with
VITE_API_PROXY_TARGET). Register http://localhost:5173/api/v1/auth/callback as redirect URI
at your identity provider (or set OIDC_REDIRECT_URL).
Configuration
All configuration is done via environment variables (a .env file in backend/ is loaded
automatically).
| Variable | Default | Description |
|---|---|---|
DB_DRIVER |
sqlite |
sqlite, mysql, postgres or mssql |
DB_NAME |
./database.db |
database name or sqlite file |
DB_HOST, DB_PORT, DB_USER, DB_PASSWORD |
connection for mysql/postgres/mssql | |
DB_SSLMODE, DB_TIMEZONE |
disable, Local |
postgres only |
DB_ENCRYPT, DB_TRUST_SERVER_CERTIFICATE |
disable, true |
mssql only |
EXECUTE_MIGRATIONS |
true |
run auto migrations and seed defaults on startup |
OIDC_ISSUER_URL, OIDC_CLIENT_ID |
required for login | |
OIDC_CLIENT_SECRET |
client secret (confidential clients) | |
OIDC_REDIRECT_URL |
derived from request | callback URL, /api/v1/auth/callback |
OIDC_EXTRA_SCOPES |
additional scopes, e.g. groups |
|
OIDC_GROUPS_CLAIM |
groups |
claim containing the group list |
OIDC_ADMIN_GROUPS |
comma separated groups granting admin (exact match) | |
OIDC_ADMIN_EMAILS |
comma separated emails granting admin | |
OIDC_USER_GROUPS |
if set, only these groups (and admins) may log in | |
SESSION_LIFETIME_HOURS |
12 |
session lifetime |
COOKIE_SECURE |
false |
set true when served via HTTPS |
TRUSTED_PROXIES |
none | comma separated proxy CIDRs for client IP detection |
PORT |
8080 |
listen port |
SMTP_HOST |
SMTP server, mails are disabled if empty | |
SMTP_PORT |
587 (465 for tls) |
SMTP port |
SMTP_SECURITY |
starttls |
starttls, tls (implicit TLS) or none |
SMTP_USERNAME, SMTP_PASSWORD |
SMTP login (PLAIN auth) | |
SMTP_FROM |
SMTP_USERNAME |
sender, e.g. Schadensmeldung <noreply@example.org> |
WEBPUSH_ENABLED |
true |
set false to disable push notifications |
VAPID_SUBJECT |
SMTP_FROM address or APP_URL |
contact (mailto: or https: URL) sent to push services |
VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY |
generated | VAPID key pair for Web Push |
MPFEUER_DB_HOST |
MP-Feuer SQL Server, hand-over is disabled if empty | |
MPFEUER_DB_PORT |
1433 |
SQL Server port |
MPFEUER_DB_NAME |
mpfeuer |
database name |
MPFEUER_DB_USER, MPFEUER_DB_PASSWORD |
SQL login | |
MPFEUER_DB_ENCRYPT, MPFEUER_DB_TRUST_SERVER_CERTIFICATE |
disable, true |
connection encryption |
MPFEUER_DB_SCHEMA |
dbo |
schema of the MP-Feuer tables |
MPFEUER_PREFIXES |
GAS,GEL,GFU,GHR,GMP,GSL,GSO,KLD |
device table prefixes searched for barcodes |
MPFEUER_HANDZEICHEN |
SM |
Handzeichen of this application in MP-Feuer |
APP_URL |
public URL used for links in mails, e.g. https://schaden.example.org |
|
FRONTEND_DIST_DIR |
../frontend/dist |
serve a built frontend from the backend |
Groups are read from both the ID token and the userinfo endpoint. The resolved groups are logged
on every login, which helps to find the exact values for OIDC_ADMIN_GROUPS.
Development
cd backend && go test ./... # unit and API integration tests (sqlite)
cd backend && swag init --parseInternal # regenerate swagger docs after changing annotations
cd frontend && yarn typecheck && yarn build
Deployment
Dockerfile.backendbuilds the backend binary into a scratch image.Dockerfile.frontendbuilds the SPA and serves it with nginx (container/nginx.conf).- The Helm chart in helm deploys both, routes
/apito the backend via ingress and optionally deploys MariaDB.