Wenn du in einem Unternehmen arbeitest, das mehr als eine Handvoll Services betreibt, kennst du das Problem bereits. Jemand tritt dem Team bei und fragt: “Von welchen Services hängt der Checkout-Prozess ab?” Niemand hat eine aktuelle Antwort. Das Architekturdiagramm im Wiki war 2022 korrekt. Der Tech Lead gibt eine mündliche Übersicht aus dem Gedächtnis, wahrscheinlich mit zwei vergessenen Details. Zwei Wochen später macht der neue Entwickler eine Änderung, die einen Service kaputtmacht, den niemand erwähnt hat.
Das ist kein Personalproblem. Es ist ein Tooling-Problem. Architekturdokumentation veraltet in dem Moment, in dem sie geschrieben wird, weil sie ausserhalb der Codebasis lebt. Die Services entwickeln sich weiter; das Diagramm nicht.
Service Map löst das, indem es eine Reihe von YAML-Dateien zur Quelle der Wahrheit macht, die zusammen mit dem Code im Repository liegen. Aus diesen Dateien generiert es einen interaktiven, filterbaren, immer aktuellen Abhängigkeitsgraphen, den jeder Entwickler im Browser öffnen, erkunden und per Link teilen kann. Kein Backend erforderlich. Kein SaaS-Abonnement. Keine Daten verlassen jemals deine Infrastruktur.
Was Service Map macht
Service Map ist ein selbst-gehostetes Visualisierungstool, das YAML-Service-Definitionen liest und als interaktiven Graphen rendert. Jeder Knoten im Graphen ist ein Service. Kanten repräsentieren Abhängigkeiten. Der Graph ist live — filtere ihn, fokussiere auf eine Teilmenge, fahre über einen Knoten, um seine gesamte Upstream- und Downstream-Kette zu verfolgen, und kopiere eine teilbare URL, die alles über die aktuelle Ansicht kodiert.
Das Ergebnis ist eine statische Webanwendung: HTML-, CSS- und JavaScript-Dateien, die du auf einem beliebigen Static Host deployst. GitHub Pages, Netlify, Vercel, ein S3-Bucket hinter CloudFront, dein internes nginx — egal. Wenn es Dateien ausliefern kann, kann es Service Map hosten. Null laufende Infrastrukturkosten.
Services werden in YAML definiert. Das Format ist einfach:
id: payment-service
name: Payment Service
area: Payments
kind: api
status: active
tech: [Node.js, PostgreSQL]
owner: payments-team
depends_on:
- target: user-service
- target: fraud-detection
- target: stripe
kind: externalDas ist die vollständige Definition für einen Service. Füge eine Datei pro Service zum Verzeichnis data/services/ hinzu, führe den Build aus und deploye. Der Graph wird automatisch um den neuen Service und seine deklarierten Abhängigkeiten erweitert.
Die vier Funktionen, die es täglich nützlich machen
Filter- und Fokusmodus
Ein Abhängigkeitsgraph mit 40 Services ist Rauschen, wenn dich nur die Payment-Domäne interessiert. Die Filter-Sidebar ermöglicht es, die Ansicht gleichzeitig nach Produktbereich, Service-Status, Technologie-Stack und Team-Eigentümerschaft einzugrenzen. Nicht passende Services werden ausgeblendet, bleiben aber im Layout, um räumlichen Kontext zu geben.
Wenn du noch weiter gehen möchtest, berechnet der Fokusmodus das Layout neu und zeigt nur die passenden Services. Isolierte Knoten — Services ohne Kanten zu etwas in der gefilterten Menge — werden ausgeschlossen. Was übrig bleibt, ist ein sauberer Teilgraph genau der Services, die für deine aktuelle Frage relevant sind.
Hover-Tracing
Fahre über einen Knoten und Service Map hebt die vollständige verbundene Kette hervor: jeden Service, der in ihn einfliesst (Upstream) und jeden Service, in den er einfliesst (Downstream), und folgt dem Graphen in beide Richtungen über mehrere Hops. Alles ausserhalb dieser Kette wird ausgeblendet. Das ist die Funktion, die die Impact-Analyse schnell macht. “Wenn ich den User Service ändere, was ist sonst noch betroffen?” Drüber fahren und du hast die Antwort in unter einer Sekunde.
Teilbare URLs
Jeder Zustand der Map — welche Filter aktiv sind, welcher Service ausgewählt ist, wie die Suchanfrage lautet — ist in der URL kodiert. Teile einen Link in Slack und dein Kollege öffnet exakt dieselbe Ansicht, die du gerade siehst. Kein Screenshot, kein “Lass mich dir erklären, wie du dort hinkommst.” URL einfügen. Fertig.
Automatisches Layout
Du positionierst Knoten nicht manuell. Die Layout-Engine (ELK — Eclipse Layout Kernel) berechnet Positionen automatisch mithilfe eines geschichteten Algorithmus, der die Abhängigkeitsrichtung respektiert. Services, die von nichts abhängen, sitzen auf einer Seite; Services, von denen alles abhängt, auf der anderen. Das Ergebnis ist ein lesbarer Graph ohne manuelle Anordnungsarbeit.
Für wen es ist
Entwickler, die eine neue Codebasis einarbeiten
Die erste Woche in einem neuen Team wird damit verbracht, ein mentales Modell des Systems aufzubauen. Service Map komprimiert diesen Prozess. Anstatt READMEs zu lesen und Fragen zu stellen, um den Abhängigkeitsgraphen im Kopf zu rekonstruieren, öffnest du die Map und hast ihn vor dir. Filtere zum Bereich deines Teams. Fahre über die Services, denen du zugewiesen wurdest. Sieh, wovon sie abhängen. Sieh, was von ihnen abhängt.
Entwickler, die eine Änderung planen
Bevor du einen Service anfässt, möchtest du den Explosionsradius kennen. Hover-Tracing zeigt dir jeden nachgelagerten Verbraucher, der von einer Änderung an dem Service betroffen sein könnte, den du gerade ändern möchtest. Das ist besonders wertvoll für gemeinsam genutzte Infrastruktur-Services — Datenbanken, Auth-Services, interne SDKs — bei denen der Abhängigkeitsgraph tief und aus dem Code allein nicht offensichtlich ist.
Architekten und Tech Leads
Architekturdokumentation, die als Confluence-Seiten oder draw.io-Diagramme gepflegt wird, weicht innerhalb von Wochen von der Realität ab. Wenn die YAML-Dateien als Code behandelt und in Pull Requests überprüft werden, bleibt die Map automatisch aktuell. Architekten können den Live-Graphen als Kommunikationsmittel für Stakeholder verwenden — eine URL teilen statt eines Screenshots, und Stakeholder sehen den tatsächlichen aktuellen Zustand.
Engineering Manager und Staff Engineers
Service-Ownership-Tracking wird trivial, wenn jeder Service ein owner-Feld in seinem YAML hat. Nach Team filtern, um alles zu sehen, wofür ein bestimmtes Team verantwortlich ist. Das Statusfeld (active, deprecated, planned) verwenden, um laufende Migrationen zu verfolgen — nach deprecated Services filtern und sehen, was noch von ihnen abhängt, um ein klares Bild der verbleibenden Migrationsarbeit zu erhalten.
Der Vorteil des Self-Hostings
Die meisten Architektur-Visualisierungstools sind SaaS. Sie berechnen pro Sitzplatz, erfordern, dass deine Service-Daten auf ihren Servern liegen, und fügen eine weitere Anbieterbeziehung hinzu. Wenn ein Team von 20 Entwicklern Zugang zur Map benötigt, sind das 20 Sitzplätze zum jeweiligen Preis. Die Tools, die gut genug sind, um nützlich zu sein, sind typischerweise nicht günstig.
Service Map ist ein Einmalkauf für 99 EUR. Du erhältst den vollständigen Quellcode. Du deployst es selbst. Deine Service-Daten bleiben in deiner Infrastruktur — sie verlassen sie nie. Es gibt kein Pro-Sitzplatz-Modell, da das Deployment eine statische Website ist: Jeder mit der URL kann sie ansehen, jeder mit Repository-Zugang kann sie bearbeiten. Eine Lizenz, unbegrenzte interne Nutzung.
Deployment in der Praxis
Service Map zum Laufen zu bringen dauert unter 15 Minuten für ein Team, das bereits Node.js und pnpm installiert hat.
- Repository klonen oder herunterladen.
- Service-YAML-Dateien hinzufügen zu
data/services/, eine Datei pro Service. - Build ausführen:
pnpm install && pnpm build - Das
dist/-Verzeichnis deployen auf den Static Host deiner Wahl.
Für Teams, die GitHub verwenden, ist GitHub Pages mit einem GitHub Actions Workflow die natürliche Wahl, der die Map bei jedem Push auf den Main-Branch neu baut und deployed. Jede Änderung an einer Service-YAML-Datei löst ein neues Deployment aus und hält die Live-Map kontinuierlich aktuell.
# .github/workflows/deploy-service-map.yml
name: Service Map deployen
on:
push:
branches: [main]
paths: ['data/**']
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v3
- run: pnpm install
- run: pnpm build
- uses: actions/deploy-pages@v4
with:
folder: distDie Architektur in YAML modellieren
| Feld | Zweck | Filterverhalten |
|---|---|---|
id | Eindeutiger Bezeichner, als Kanten-Ziel in depends_on verwendet | — |
area | Produktdomäne oder Team-Bereich | Bereich-Filter |
kind | Service-Typ: api, worker, database, external usw. | Art-Filter |
status | Lebenszyklus-Status: active, deprecated, planned | Status-Filter |
tech | Technologie-Stack (Array) | Tech-Filter |
owner | Verantwortliches Team oder Person | — |
depends_on | Liste der Service-IDs, die dieser Service aufruft | Steuert Graph-Kanten |
Praxisanwendungsfälle
Incident Response
Wenn ein Service degradiert oder ausgefallen ist, ist die erste Frage immer: “Was ist sonst noch kaputt?” Öffne die Map, fahre über den betroffenen Service und du siehst sofort jeden nachgelagerten Verbraucher. Teile die URL im Incident-Kanal, damit das gesamte Response-Team denselben Graphen sieht, ohne dass jemand die Abhängigkeitsstruktur mündlich erklären muss.
Deprecation-Planung
Markiere einen Service als deprecated in seinem YAML. Filtere die Map nach deprecated Services. Der Graph zeigt dir jeden Service, der noch vom deprecated abhängt. Diese Liste ist deine Migrations-Checkliste. Während Teams ihre Abhängigkeiten migrieren, aktualisieren sie ihre eigenen Service-YAMLs. Die Map zeigt den Migrationsfortschritt in Echtzeit.
Tech-Stack-Audits
Filtere nach einer bestimmten Technologie — zum Beispiel einem Legacy-Framework, von dem du wegmigrieren möchtest. Jeder Service, der dieses Framework verwendet, erscheint. Filtere weiter nach Team, um Migrationsverantwortung zuzuweisen. Die Map wird zu einem lebendigen Audit-Dokument statt einer Tabelle, die jemand vierteljährlich aktualisiert.
Onboarding neuer Entwickler
Füge einen Link zur Service Map zu deiner Onboarding-Dokumentation hinzu. Neue Entwickler können strukturelle Fragen selbst beantworten, anstatt erfahrene Entwickler zu unterbrechen. “Wie funktioniert das Benachrichtigungssystem?” — nach dem Benachrichtigungsbereich filtern und den Graphen verfolgen. Die meisten Fragen beantworten sich innerhalb von zwei Minuten Erkundung selbst.
Architektur-Reviews
Du schlägst einen neuen Service oder ein grösseres Refactoring vor? Füge den neuen Service in einem Branch zum YAML hinzu, baue lokal und teile einen Link, der die vorgeschlagene Architektur zeigt. Reviewer sehen den konkreten Graphen, anstatt eine schriftliche Beschreibung zu lesen. Randfälle (zirkuläre Abhängigkeiten, unerwartete Kopplung) sind in Graphform sofort sichtbar.
Vergleich mit Alternativen
| Service Map | Backstage | SaaS-Diagrammtools | Wiki-Diagramme | |
|---|---|---|---|---|
| Einrichtungszeit | Unter 15 Min. | Tage bis Wochen | Minuten | Minuten |
| Bleibt aktuell | Ja (YAML im Repo) | Ja (Katalog) | Nein (manuell) | Nein (manuell) |
| Self-hosted | Ja | Ja | Nein | Abhängig |
| Daten verlassen Org | Nein | Nein | Ja | Abhängig |
| Pro-Sitzplatz-Kosten | Nein | Nein | Typischerweise ja | Nein |
| Einmalkosten | 99 EUR | Kostenlos (OSS) | Abonnement | Im Wiki enthalten |
| Hover-Tracing | Ja | Nein | Variiert | Nein |
| Teilbare URLs | Ja | Ja | Variiert | Nein |
| Fokusmodus | Ja | Nein | Variiert | Nein |
Was im Lieferumfang enthalten ist
- Vollständiger TypeScript-Quellcode — gebaut mit Vite, React, ReactFlow und ELK. Lesbar, typisiert und einfach zu erweitern.
- Vorgefertigte statische Dateien — sofort deployen ohne eigenen Build-Schritt.
- Beispiel-Service-Daten — ein realistischer Satz von Beispiel-Service-Definitionen zum Verständnis des Formats und zum Testen von Filtern.
- Dokumentation — deckt das YAML-Schema, alle Konfigurationsoptionen und Deployment-Anweisungen ab.
- Ein Jahr Updates — neue Funktionen und Bugfixes für 12 Monate nach dem Kauf via
git pull. - Unbegrenzte interne Nutzung — eine Lizenz deckt deine gesamte Organisation ab.
Häufig gestellte Fragen
Wie viele Services kann es verarbeiten?
Die Layout-Engine funktioniert gut bis zu einigen Hundert Knoten. Für Organisationen mit sehr grossen Service-Zahlen (500+) werden Fokusmodus und Filterung essenziell — der vollständige Graph wird gerendert, aber die Navigation ist am praktischsten, wenn sie auf eine sinnvolle Teilmenge gefiltert wird.
Kann ich das visuelle Erscheinungsbild anpassen?
Ja. Design-Tokens für Bereichsfarben, Kantenfarben, Status-Badge-Farben und Art-Icons sind in src/graph/styles.ts zentralisiert. Das Hinzufügen eines neuen Bereichs oder Service-Typs erfordert die Aktualisierung dieser Datei und der Schema-Enum. Der Quellcode ist TypeScript — wenn du ihn lesen kannst, kannst du ihn ändern.
Unterstützt es Teams mit mehreren Repositories?
Service Map ist ein einzelnes Deployment mit einem einzelnen data/-Verzeichnis. Das natürliche Muster für Multi-Repo-Teams ist ein dediziertes “Service-Katalog”-Repository, das YAML-Dateien aus der gesamten Organisation aggregiert. Teams öffnen Pull Requests zum Katalog-Repo, wenn sie Services hinzufügen oder ändern.
Was passiert nach Ablauf des Jahres Updates?
Die Version, die du hast, funktioniert auf unbestimmte Zeit weiter. Du besitzt den Quellcode. Nach 12 Monaten hörst du auf, neue Funktionen und Bugfixes zu erhalten, sofern du nicht verlängerst oder eine neue Lizenz kaufst.
Ist Authentifizierung eingebaut?
Service Map selbst hat keine Authentifizierungsschicht — es ist eine statische Website. Zugriffskontrolle wird auf Hosting-Ebene gehandhabt. Für reinen internen Zugriff deploye hinter deinem VPN, einer Cloudflare Access-Regel oder Basic Auth auf CDN-/Webserver-Ebene.
Wie lautet die Rückgaberichtlinie?
Standard 14-Tage-Rückgaberichtlinie. Wenn es für deinen Anwendungsfall nicht funktioniert, kontaktiere den Support innerhalb von 14 Tagen nach dem Kauf für eine vollständige Rückerstattung.
Architekturdrift ist eines jener Probleme, das jedes Engineering-Team hat und die meisten Teams tolerieren statt beheben, weil die verfügbaren Lösungen entweder zu schwergewichtig (Backstage) oder zu passiv (Wiki-Diagramme) sind. Service Map sitzt in der Lücke: leichtgewichtig genug, um es an einem Nachmittag zu deployen, leistungsfähig genug, um Abhängigkeitsfragen in Sekunden beantwortbar zu machen, und günstig genug, dass die Kosten-Nutzen-Berechnung keine schwierige ist.
Für 99 EUR einmalig für unbegrenzte interne Nutzung zahlt sich das Tool beim ersten Mal aus, wenn es einen Produktionsvorfall durch eine undokumentierte Abhängigkeit verhindert.
