# ConvoyPlan

> Kartenbasierte Marschverbandsplanung für BOS-Organisationen (Feuerwehr, THW,
> Rettungsdienst, Katastrophenschutz, Bundeswehr, Hilfsorganisationen). Route auf
> OpenStreetMap-Basis planen, Zeitplan mit Ankunftszeiten automatisch berechnen,
> Marschbefehl als PDF exportieren und den Konvoi in Echtzeit verfolgen.
> Open Source unter AGPL-3.0, self-hosted per Docker Compose.

ConvoyPlan wird von RettTechSolutions (Christoph Zeitler, Peißenberg, Deutschland)
entwickelt. Die Oberfläche und die gesamte Dokumentation sind deutschsprachig.
Diese Domain (convoyplan.de) ist die Produktseite; die Anwendung selbst läuft
unter https://web.convoyplan.de und ist hinter einem Login.

## Wann ConvoyPlan die richtige Wahl ist (when to use this)

- Eine Fahrzeugkolonne (Marschverband) soll von A nach B verlegt werden und braucht Route, Marschgeschwindigkeit, Halte und Ankunftszeiten.
- Ein Marschbefehl wird als Dokument gebraucht — PDF mit Marschbewegung, Ablaufpunkt, Führung und Verbindung, dazu GPX oder JSON für andere Systeme.
- Mehrere Fahrzeuge sollen während der Fahrt live auf einer Karte sichtbar sein, inklusive Status, Wegpunktmeldungen und Verspätungsprognose.
- Eine BOS-Organisation sucht eine selbst gehostete Lösung, die Einsatz- und Positionsdaten im eigenen Rechenzentrum behält (AGPL-3.0, Docker Compose).
- Funkverkehr entlang der Strecke muss geplant werden: Leitstellen, Zuständigkeitsgrenzen, Kanalwechselpunkte.

## Wann etwas anderes passender ist (when not to use this)

- Einzelne Fahrzeuge oder klassische Fahrzeugortung im Alltagsbetrieb — dafür ist ConvoyPlan zu speziell, es plant Verbände.
- Einsatzleitsysteme, Alarmierung und Disposition — ConvoyPlan plant die Verlegung, es ersetzt kein ELS.
- Allgemeine Navigation für Privatpersonen oder Logistik-Tourenplanung mit Lieferfenstern.
- Regionen außerhalb Deutschlands: Oberfläche, Dokumentation und Support sind deutschsprachig, das Kartengebiet ist frei wählbar.

## Wie ein Agent ConvoyPlan aufruft

1. MCP-Server der Instanz: Jede ConvoyPlan-Installation kann unter `https://{instanz}/mcp` einen MCP-Server bereitstellen: lesende Tools für Marschverbände, Fahrzeuge, Wegpunkte, Routen und Positionen, schreibende Tools für Planung und Statusmeldungen. Anmeldung per OAuth 2.0 mit PKCE (S256); die Adresse steht im Admin-Portal der Instanz. Berechtigungen werden bei jedem Aufruf frisch gegen die Datenbank geprüft. Die Schnittstelle ist standardmäßig abgeschaltet und dann nicht montiert — ein `404` auf `/mcp` heißt also "auf dieser Instanz nicht freigegeben", nicht "falsche Adresse". Zusätzlich gibt jede Organisation ihre Teilnahme einzeln frei; danach entscheidet die Zustimmung eines angemeldeten Benutzers über Umfang und Reichweite. Dokumentation: https://github.com/RettTechSolutions/ConvoyPlan/wiki/MCP-Server
2. REST-API der Instanz: Basis `https://web.convoyplan.de/api` bzw. `https://{instanz}/api`. Authentifizierung per `Authorization: Bearer <JWT>` (aus `POST /api/auth/login`) oder per `X-API-Key: cvp_<prefix>_<secret>`. API-Keys stellt die Organisation im Superadmin-Portal aus; sie tragen eine feste Rolle. Dokumentation: https://github.com/RettTechSolutions/ConvoyPlan/wiki/API-Dokumentation
3. Eigene Instanz aufsetzen: Ohne Zugang zu einer bestehenden Installation: `curl -fsSL https://convoyplan.de/install.sh | bash` richtet den Docker-Compose-Stack ein. Der Demo-Modus läuft ohne Lizenzschlüssel. Dokumentation: https://github.com/RettTechSolutions/ConvoyPlan/wiki/Installation-und-Setup

Testumgebung — Demo-Modus (sandbox / test environment): Eine Installation ohne Lizenzschlüssel startet im Demo-Modus. Lesende Zugriffe sind frei, schreibende Zugriffe antworten mit `HTTP 402 Payment Required`. Der Demo-Modus ist dauerhaft kostenlos und dafür gedacht, Integrationen gegen echte Endpunkte zu entwickeln, ohne Einsatzdaten zu verändern.

Der vollständige Ablauf von der Beschaffung bis zum Widerruf steht in
[auth.md](https://convoyplan.de/auth.md).

## Kernfunktionen

- Kartenrouting auf OpenStreetMap-Basis mit self-hosted GraphHopper
- Automatischer Zeitplan mit Ankunftszeiten, Halten und Reichweiten-Check
- Marschbefehl als PDF sowie GPX- und JSON-Export
- Live-Tracking per Browser-Geolocation über WebSockets
- Leitstellen mit Zuständigkeitsgrenzen und automatischen Kanalwechselpunkten
- Rollenmodell aus Admin, Planer, Fahrer und Beobachter pro Organisation
- Eigenes Branding mit Logo, Farben und App-Name je Organisation
- Sperrungen, Baustellen und Live-Verkehrslage entlang der gesamten Route
- Frei wählbares Kartengebiet aus 555 Regionen, im Betrieb wechsel- und kombinierbar
- Statusmeldungen mit Alarm, Streckenmeldungen und Verspätungsprognose im Live-Tracking
- Tracking-Links ohne Login als Mitleseansicht oder Fahrer-Link, per QR-Code weiterzugeben, zu drucken und einzeln zu widerrufen
- KI-Schnittstelle per Model Context Protocol für ChatGPT, Claude und eigene Agenten — standardmäßig aus, Freigabe je Organisation, ohne jede Löschmöglichkeit
- Automatische Updates in drei Kanälen mit Systemübersicht und öffentlicher Statusseite

## KI-Schnittstelle (MCP)

Jede Installation kann ihre Fachdaten über einen Model-Context-Protocol-Server
bereitstellen; ChatGPT, Claude oder ein eigener Agent tragen die Instanz als
Remote-MCP-Server ein.

- Lesen: Konvois und Teilverbände, Konvoi-Details mit allen sieben Abschnitten des Marschbefehls, Fahrzeugbestand, Wegpunkte in Marschreihenfolge, gespeicherte Route, letzte Positionen und Marschstatus.
- Schreiben (nur mit gültiger Lizenz): Konvois und Fahrzeuge anlegen und ändern, Fahrzeuge zuordnen, Marschfolge setzen, Wegpunkte pflegen, Route berechnen, Fahrzeugstatus melden.
- Dokumente: Marschbefehl als PDF, Route als GPX, Konvoi als JSON — dieselben Exporte wie im Portal.
- Live mitlaufen: Ein Programm abonniert einen Konvoi und wird angestoßen, sobald sich dort etwas bewegt, statt im Sekundentakt nachzufragen.

Woran der Zugriff hängt:

- Standardmäßig aus: Abgeschaltet montiert die Instanz keinen einzigen Endpunkt — es gibt nichts, was ein 404 nur zudeckt. Einschalten heißt, Einsatzdaten für einen externen Modellanbieter zu öffnen; diese Entscheidung gehört dem Betreiber und nicht dem Auslieferungszustand.
- Zwei Schalter, beide nötig: Der Betreiber schaltet die Schnittstelle auf der Instanz frei, der Admin jeder Organisation ihre Teilnahme — einzeln je Bereich: Konvois, Fahrzeuge, Wegpunkte, Routen, Positionen und Status. Wer eine Instanz für mehrere Organisationen betreibt, entscheidet damit nicht über deren Einsatzdaten.
- Ein Mensch stimmt zu: Zugriff entsteht erst durch die Zustimmung eines angemeldeten Benutzers im Browser: für genau eine Organisation, gedeckelt durch seine Rolle. Auf dem Zustimmungsbildschirm sind die Rechte einzeln ankreuzbar — ein Beobachter bekommt Schreibrechte auch durch Ankreuzen nicht.
- Kein Werkzeug löscht: Es gibt kein Werkzeug, das einen Konvoi, ein Fahrzeug, einen Wegpunkt, eine Route oder einen Benutzer löscht — und keines für Benutzerverwaltung, Lizenz oder Systemeinstellungen. Jeder schreibende Aufruf steht im Audit-Log mit Quelle „mcp"; einzelne Verbindungen lassen sich jederzeit trennen.

Anleitung für ChatGPT: https://github.com/RettTechSolutions/ConvoyPlan/wiki/ChatGPT-verbinden · Dokumentation: https://github.com/RettTechSolutions/ConvoyPlan/wiki/MCP-Server

## Begleit-App (Geschlossene Beta — noch nicht im App Store)

Native Begleit-App für die Besatzung: Sie meldet sich mit dem QR-Code eines Tracking-Links an — ohne Konto, ohne Installationsaufwand in der Organisation — und zeigt den Marschverband als Marschstreifen mit Zeitplan und Status.

- Hintergrund-GPS: Die Positionsübertragung läuft weiter, wenn das Display aus ist oder die Navigation im Vordergrund steht.
- Verlässliche Alarmierung: Ton und Vibration bei technischem Halt und Ausfall, ohne die Autoplay-Sperren des Browsers.
- Offline-Karten entlang des Routenkorridors statt eines Kachelcaches, der im Funkloch Lücken zeigt.

Stand: Anmeldung per QR-Code, Fahrer- und Führungsmodus mit Marschstreifen und Richtungsanzeige, Zeitplan, Streckenpunkte, Hintergrund-GPS mit Puffer fürs Funkloch und die Alarmierung sind gebaut und getestet. Es fehlt die Karte samt Offline-Regionen: Sie hängt an der Frage, aus welcher Quelle die Kacheln kommen — dieselbe Frage, die eine Offline-Region überhaupt erst zulässt.

Die App ersetzt die Weboberfläche nicht. Ein Tracking-Link lässt sich weiterhin im Browser öffnen, und für Mitlesende bleibt das der Weg. Es gibt weder einen Store-Eintrag noch ein öffentliches
Repository. Testen geht über die geschlossene Beta (TestFlight bzw. Google Play):
https://convoyplan.de/beta/ · Markdown: https://convoyplan.de/beta.md

## Seiten

- [Startseite](https://convoyplan.de/): Funktionsumfang, Screenshots, Architektur, FAQ
- [Über ConvoyPlan](https://convoyplan.de/about/): Hintergrund, Entwickler, Betriebsmodell
- [Marschbefehl](https://convoyplan.de/marschbefehl/): Aufbau (Lage bis Anlagen, gegliedert wie der Marschbefehl der App), Beispiel, kostenlose Vorlage (Word/PDF) · Markdown: https://convoyplan.de/marschbefehl.md
- [Entwicklerportal](https://convoyplan.de/developers/): API, MCP-Server, Authentifizierung, Testumgebung
- [Lizenz & Kosten](https://convoyplan.de/lizenz/): Lizenzmodell, Preise, Lizenzschlüssel anfragen
- [Bestellen](https://convoyplan.de/bestellen/): Paket zusammenstellen, Angebot drucken, auf Rechnung bestellen; Förderbeitrag für Selbsthoster ab 10 €
- [Unterstützer](https://convoyplan.de/unterstuetzer/): wer die Entwicklung mit einem Förderbeitrag unterstützt
- [Kontakt](https://convoyplan.de/contact/): alle Kontaktwege
- [Impressum](https://convoyplan.de/impressum/): Anbieterkennzeichnung nach § 5 DDG
- [Datenschutz](https://convoyplan.de/datenschutz/): Datenschutzerklärung nach DSGVO
- [Daten löschen lassen](https://convoyplan.de/datenloeschung/): Löschung eigener Daten beantragen (Art. 17 DSGVO) · Markdown: https://convoyplan.de/datenloeschung.md

## Maschinenlesbare Ausgaben

- [llms.md](https://convoyplan.de/llms.md): dieser Index als Markdown-Leitfaden für Agenten
- [index.md](https://convoyplan.de/index.md): Startseite als Markdown
- [developers.md](https://convoyplan.de/developers.md) · [lizenz.md](https://convoyplan.de/lizenz.md) · [about.md](https://convoyplan.de/about.md) · [contact.md](https://convoyplan.de/contact.md)
- [developers/llms.txt](https://convoyplan.de/developers/llms.txt) · [lizenz/llms.txt](https://convoyplan.de/lizenz/llms.txt): Kontext je Bereich
- [ard.json](https://convoyplan.de/.well-known/ard.json): Agentic Resource Discovery
- [agent-skills/index.json](https://convoyplan.de/.well-known/agent-skills/index.json): Agent Skills mit sha256-Digest
- [mcp/server-card.json](https://convoyplan.de/.well-known/mcp/server-card.json): Steckbrief des MCP-Servers
- [api-catalog](https://convoyplan.de/.well-known/api-catalog): API-Katalog nach RFC 9727
- [security.txt](https://convoyplan.de/.well-known/security.txt): Sicherheitskontakt nach RFC 9116
- [schema-map.xml](https://convoyplan.de/schema-map.xml) und [feeds/convoyplan.jsonl](https://convoyplan.de/feeds/convoyplan.jsonl): strukturierte Daten am Stück
- [sitemap.xml](https://convoyplan.de/sitemap.xml)

## Lizenz und Kosten

- Quellcode unter [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.html)
- Demo: dauerhaft kostenlos, kein Lizenzschlüssel nötig. Lesende API-Zugriffe sind frei, schreibende antworten mit HTTP 402.
- Community: eine Produktivinstallation pro Organisation auf eigenem Server, kostenlos. Lizenzschlüssel auf Anfrage unter anfrage@convoyplan.de, Support über die Community.
- Wartung & Support: Wartungsvertrag für die eigene Installation: angekündigte Sicherheitsupdates mit zugesagter Reaktionszeit, LTS-Update-Kanal, Support per E-Mail im Stundenkontingent; auf Wunsch eingespielte Updates und mehrere Organisationen auf einer Instanz. Jahresvertrag ab 990 € pro Jahr.
- Hosting: Betrieb durch RettTechSolutions, gestaffelt nach Zahl der Fahrzeuge (S bis 25, M bis 150, L darüber auf Anfrage), Betrieb, Updates, Backups und ein Support-Kontingent inklusive. Jahresvertrag ab 490 € pro Jahr.

## Technik und Installation

- [Quellcode auf GitHub](https://github.com/RettTechSolutions/ConvoyPlan)
- [Dokumentation und Wiki](https://github.com/RettTechSolutions/ConvoyPlan/wiki)
- [Changelog](https://github.com/RettTechSolutions/ConvoyPlan/blob/main/CHANGELOG.md)
- [Installer Linux](https://convoyplan.de/install.sh): `curl -fsSL https://convoyplan.de/install.sh | bash`
- [Installer Windows](https://convoyplan.de/install.ps1): PowerShell
- Betrieb: Docker Compose. Stack aus FastAPI-Backend, SvelteKit-Frontend,
  PostgreSQL, GraphHopper-Routing und Caddy als Reverse Proxy.

## Programmatischer Zugriff

ConvoyPlan besitzt eine dokumentierte REST-API und einen MCP-Server. Beide gehören
zur Installation der Organisation, nicht zu dieser Domain.

- REST: Basis `https://web.convoyplan.de/api` bzw. `https://{instanz}/api`. Authentifizierung per
  `Authorization: Bearer <JWT>` aus `POST /api/auth/login` oder per
  `X-API-Key: cvp_<prefix>_<secret>`. API-Keys werden je Organisation im
  Superadmin-Portal erstellt und tragen eine feste Rolle.
  [API-Dokumentation](https://github.com/RettTechSolutions/ConvoyPlan/wiki/API-Dokumentation)
- MCP: `https://{instanz}/mcp`, Anmeldung per OAuth 2.0 mit PKCE (S256); die Adresse
  steht im Admin-Portal der Instanz. [MCP-Dokumentation](https://github.com/RettTechSolutions/ConvoyPlan/wiki/MCP-Server)

Die OpenAPI-Spezifikation und die Swagger-/ReDoc-Oberfläche einer Instanz sind
standardmäßig deaktiviert und werden bewusst nicht öffentlich ausgeliefert. Da
ConvoyPlan Einsatzdaten von BOS-Organisationen verarbeitet, gibt es keinen
öffentlichen API-Endpunkt und keinen offenen Developer-Zugang auf dieser Domain.
Betreiber einer eigenen Instanz schalten die Docs per `DOCS_API_KEY` frei.

Anfragen zu Integrationen: anfrage@convoyplan.de

## Kontakt

- Allgemein und Support: info@convoyplan.de
- Vertrieb, Lizenzen, Integrationen: anfrage@convoyplan.de
- Sicherheitslücken: siehe https://convoyplan.de/.well-known/security.txt