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

  1. Melden Sie sich bei Archyl an
  2. Klicken Sie auf den "+ Neues Projekt"-Button
  3. 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")
  4. 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

  1. In der leeren Leinwand klicken Sie auf "+" oder rechtsklicken
  2. Wählen Sie "System hinzufügen"
  3. Geben Sie ein:
    • Name: Der Name Ihres Systems
    • Beschreibung: Was es macht
    • Typ: Intern (Sie besitzen es)

Benutzer Hinzufügen

  1. Klicken Sie auf "+" und wählen Sie "Person hinzufügen"
  2. Erstellen Sie jeden Benutzertyp:
    • Name: "Kunde", "Admin-Benutzer", etc.
    • Beschreibung: Ihre Rolle und was sie tun

Externe Systeme Hinzufügen

  1. Klicken Sie auf "+" und wählen Sie "Externes System hinzufügen"
  2. Für jede externe Abhängigkeit:
    • Name: "Stripe", "SendGrid", etc.
    • Beschreibung: Was es bereitstellt

Beziehungen Erstellen

  1. Fahren Sie über das Quellelement
  2. Ziehen Sie vom Verbindungspunkt zum Ziel
  3. Fügen Sie ein Label hinzu: "Bestellt über", "Sendet E-Mails durch", etc.
  4. 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:

  1. Klicken Sie auf "+" und wählen Sie "Container hinzufügen"
  2. 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:

  1. Doppelklicken Sie auf einen Container
  2. 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

  1. Gehen Sie zu Projekteinstellungen → Repository
  2. Verbinden Sie Ihren Git-Anbieter
  3. Wählen Sie Ihr Repository

Entdeckung Starten

  1. Klicken Sie auf "Entdeckung starten"
  2. Warten Sie, bis die Analyse abgeschlossen ist
  3. Überprüfen Sie ausstehende Entdeckungen

Überprüfen & Genehmigen

  1. Prüfen Sie jedes entdeckte Element
  2. Bearbeiten Sie Namen/Beschreibungen bei Bedarf
  3. Genehmigen Sie genaue Elemente
  4. 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:

  1. Gehen Sie zum ADRs-Bereich
  2. Klicken Sie auf "Neuer ADR"
  3. 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

  1. Gehen Sie zu Projekteinstellungen → Team
  2. Klicken Sie auf "Einladen"
  3. Geben Sie E-Mail-Adressen ein
  4. Weisen Sie Rollen zu (Betrachter, Editor, Admin)

Share-Links Erstellen

Für Stakeholder ohne Konto:

  1. Klicken Sie auf "Teilen" in der Toolbar
  2. Konfigurieren Sie Zugriffsoptionen
  3. Kopieren und teilen Sie den Link

Diagramme Exportieren

Für Präsentationen oder Dokumente:

  1. Klicken Sie auf "Exportieren"
  2. Wählen Sie Format (PNG, SVG, PDF)
  3. 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: