Ihr Erstes Projekt Erstellen
Diese umfassende Anleitung begleitet Sie bei der Erstellung Ihres ersten Architekturdokumentationsprojekts in Archyl, von der Ersteinrichtung bis zum Teilen mit Ihrem Team.
Voraussetzungen
Bevor Sie beginnen:
- Ein Archyl-Konto (hier registrieren)
- Ein Softwaresystem, das Sie dokumentieren möchten
- Optional: Zugriff auf Ihr Code-Repository
Schritt 1: Ein Neues Projekt Erstellen
Vom Dashboard
- Melden Sie sich bei Archyl an
- Klicken Sie auf den "+ Neues Projekt"-Button
- Geben Sie Ihre Projektdetails ein:
- Name: Ein klarer, beschreibender Name (z.B. "E-Commerce-Plattform")
- Beschreibung: Kurzer Überblick über das System
- Tags: Schlüsselwörter zur Organisation (z.B. "backend", "microservices")
- Klicken Sie auf "Projekt erstellen"
Projekteinstellungen
Nach der Erstellung konfigurieren Sie Ihr Projekt:
- Sichtbarkeit: Öffentlich oder privat
- Team-Zugriff: Welche Teams können sehen/bearbeiten
- Repository: Für KI-Entdeckung verbinden (optional)
Schritt 2: Den Systemkontext Verstehen
Bevor Sie Diagramme zeichnen, verstehen Sie den Kontext Ihres Systems:
Benutzer Identifizieren
Wer nutzt Ihr System?
- Endbenutzer (Kunden, Mitarbeiter)
- Administratoren
- Externe Entwickler
- Andere Systeme
Externe Systeme Identifizieren
Womit interagiert Ihr System?
- Zahlungsabwickler
- Authentifizierungsanbieter
- E-Mail/Benachrichtigungsdienste
- Analytics-Plattformen
- Partner-APIs
Schritt 3: Das Systemkontext-Diagramm Erstellen
Ihr Hauptsystem Hinzufügen
- In der leeren Leinwand klicken Sie auf "+" oder rechtsklicken
- Wählen Sie "System hinzufügen"
- Geben Sie ein:
- Name: Der Name Ihres Systems
- Beschreibung: Was es macht
- Typ: Intern (Sie besitzen es)
Benutzer Hinzufügen
- Klicken Sie auf "+" und wählen Sie "Person hinzufügen"
- Erstellen Sie jeden Benutzertyp:
- Name: "Kunde", "Admin-Benutzer", etc.
- Beschreibung: Ihre Rolle und was sie tun
Externe Systeme Hinzufügen
- Klicken Sie auf "+" und wählen Sie "Externes System hinzufügen"
- Für jede externe Abhängigkeit:
- Name: "Stripe", "SendGrid", etc.
- Beschreibung: Was es bereitstellt
Beziehungen Erstellen
- Fahren Sie über das Quellelement
- Ziehen Sie vom Verbindungspunkt zum Ziel
- Fügen Sie ein Label hinzu: "Bestellt über", "Sendet E-Mails durch", etc.
- Optional Technologie hinzufügen: "REST/HTTPS", "SMTP"
Schritt 4: In Container Eintauchen
Die Container-Ansicht Öffnen
Doppelklicken Sie auf Ihr Hauptsystem, um zur Container-Ebene zu zoomen.
Container Identifizieren
Was sind die technischen Bausteine?
- Anwendungen: Web-App, Mobile-App, Desktop-Client
- Services: API-Server, Hintergrund-Worker
- Datenspeicher: Datenbanken, Caches, Dateispeicher
- Nachrichtenwarteschlangen: Event-Busse, Queues
Container Hinzufügen
Für jeden Container:
- Klicken Sie auf "+" und wählen Sie "Container hinzufügen"
- Geben Sie ein:
- Name: "Webanwendung", "API-Server", "PostgreSQL"
- Beschreibung: Seine Verantwortung
- Technologie: "React", "Node.js", "PostgreSQL 15"
Container Verbinden
Zeigen Sie, wie Container kommunizieren:
- Web-App → API-Server: "Macht API-Aufrufe [REST/HTTPS]"
- API-Server → Datenbank: "Liest/schreibt Daten [SQL]"
- API-Server → Cache: "Cached Session-Daten [Redis-Protokoll]"
Schritt 5: Komponenten Hinzufügen (Optional)
Für kritische Container zoomen Sie in Komponenten:
- Doppelklicken Sie auf einen Container
- Fügen Sie Komponenten hinzu, die wichtige Module repräsentieren:
- Controller
- Services
- Repositories
- Utilities
Schritt 6: KI-Entdeckung Verwenden (Optional)
Lassen Sie KI bei der Dokumentation Ihrer Architektur helfen:
Repository Verbinden
- Gehen Sie zu Projekteinstellungen → Repository
- Verbinden Sie Ihren Git-Anbieter
- Wählen Sie Ihr Repository
Entdeckung Starten
- Klicken Sie auf "Entdeckung starten"
- Warten Sie, bis die Analyse abgeschlossen ist
- Überprüfen Sie ausstehende Entdeckungen
Überprüfen & Genehmigen
- Prüfen Sie jedes entdeckte Element
- Bearbeiten Sie Namen/Beschreibungen bei Bedarf
- Genehmigen Sie genaue Elemente
- Lehnen Sie ungenaue ab oder ändern Sie sie
Schritt 7: Dokumentation Hinzufügen
Elementbeschreibungen
Klicken Sie auf ein beliebiges Element und fügen Sie detaillierte Beschreibungen hinzu:
- Zweck und Verantwortlichkeiten
- Getroffene Schlüsselentscheidungen
- Wichtige Hinweise
Architecture Decision Records
Dokumentieren Sie wichtige Entscheidungen:
- Gehen Sie zum ADRs-Bereich
- Klicken Sie auf "Neuer ADR"
- Füllen Sie aus:
- Titel: "PostgreSQL für Persistenz verwenden"
- Kontext: Warum diese Entscheidung nötig war
- Entscheidung: Was entschieden wurde
- Konsequenzen: Auswirkungen der Entscheidung
Dokumentation Verknüpfen
Verknüpfen Sie ADRs und Docs mit spezifischen Elementen für Kontext.
Schritt 8: Mit Ihrem Team Teilen
Teammitglieder Einladen
- Gehen Sie zu Projekteinstellungen → Team
- Klicken Sie auf "Einladen"
- Geben Sie E-Mail-Adressen ein
- Weisen Sie Rollen zu (Betrachter, Editor, Admin)
Share-Links Erstellen
Für Stakeholder ohne Konto:
- Klicken Sie auf "Teilen" in der Toolbar
- Konfigurieren Sie Zugriffsoptionen
- Kopieren und teilen Sie den Link
Diagramme Exportieren
Für Präsentationen oder Dokumente:
- Klicken Sie auf "Exportieren"
- Wählen Sie Format (PNG, SVG, PDF)
- Laden Sie Ihre Diagramme herunter
Best Practices
Einfach Starten
- Beginnen Sie mit dem Systemkontext
- Fügen Sie schrittweise Details hinzu
- Versuchen Sie nicht, alles auf einmal zu dokumentieren
Aktuell Halten
- Aktualisieren Sie bei Architekturänderungen
- Führen Sie KI-Entdeckung nach größeren Änderungen aus
- Überprüfen Sie regelmäßig mit Ihrem Team
Auf Kommunikation Fokussieren
- Verwenden Sie klare, beschreibende Namen
- Fügen Sie Kontext in Beschreibungen hinzu
- Zeigen Sie die wichtigsten Beziehungen
Nächste Schritte
Herzlichen Glückwunsch! Sie haben Ihre erste Architekturdokumentation erstellt. Lernen Sie weiter: