Creare il Tuo Primo Progetto - Archyl Docs

Una guida passo passo per creare e documentare il tuo primo progetto di architettura in Archyl

Creare il Tuo Primo Progetto

Questa guida completa ti accompagna nella creazione del tuo primo progetto di documentazione architetturale in Archyl, dalla configurazione iniziale alla condivisione con il tuo team.

Prerequisiti

Prima di iniziare:

  • Un account Archyl (registrati qui)
  • Un sistema software da documentare
  • Opzionale: Accesso al repository della codebase

Passo 1: Creare un Nuovo Progetto

Dalla Dashboard

  1. Accedi ad Archyl
  2. Clicca il pulsante "+ Nuovo Progetto"
  3. Inserisci i dettagli del progetto:
    • Nome: Un nome chiaro e descrittivo (es. "Piattaforma E-commerce")
    • Descrizione: Panoramica breve del sistema
    • Tag: Parole chiave per l'organizzazione (es. "backend", "microservizi")
  4. Clicca "Crea Progetto"

Impostazioni del Progetto

Dopo la creazione, configura il progetto:

  • Visibilità: Pubblico o privato
  • Accesso del team: Quali team possono visualizzare/modificare
  • Repository: Collega per la scoperta IA (opzionale)

Passo 2: Comprendere il Contesto del Sistema

Prima di disegnare i diagrammi, comprendi il contesto del tuo sistema:

Identificare gli Utenti

Chi usa il tuo sistema?

  • Utenti finali (clienti, dipendenti)
  • Amministratori
  • Sviluppatori esterni
  • Altri sistemi

Identificare i Sistemi Esterni

Con cosa interagisce il tuo sistema?

  • Processori di pagamento
  • Provider di autenticazione
  • Servizi email/notifiche
  • Piattaforme di analytics
  • API dei partner

Passo 3: Creare il Diagramma del Contesto del Sistema

Aggiungere il Sistema Principale

  1. Nel canvas vuoto, clicca "+" o fai clic destro
  2. Seleziona "Aggiungi Sistema"
  3. Inserisci:
    • Nome: Il nome del tuo sistema
    • Descrizione: Cosa fa
    • Tipo: Interno (lo possiedi tu)

Aggiungere Utenti

  1. Clicca "+" e seleziona "Aggiungi Persona"
  2. Crea ogni tipo di utente:
    • Nome: "Cliente", "Utente Admin", ecc.
    • Descrizione: Il loro ruolo e cosa fanno

Aggiungere Sistemi Esterni

  1. Clicca "+" e seleziona "Aggiungi Sistema Esterno"
  2. Per ogni dipendenza esterna:
    • Nome: "Stripe", "SendGrid", ecc.
    • Descrizione: Cosa fornisce

Creare Relazioni

  1. Passa il mouse sull'elemento sorgente
  2. Trascina dal punto di connessione alla destinazione
  3. Aggiungi un'etichetta: "Effettua ordini tramite", "Invia email attraverso", ecc.
  4. Opzionalmente aggiungi la tecnologia: "REST/HTTPS", "SMTP"

Passo 4: Approfondire nei Contenitori

Aprire la Vista Contenitori

Fai doppio clic sul sistema principale per entrare nel livello Contenitore.

Identificare i Contenitori

Quali sono i blocchi tecnici di costruzione?

  • Applicazioni: App web, app mobile, client desktop
  • Servizi: Server API, worker in background
  • Archivi dati: Database, cache, archiviazione file
  • Code di messaggi: Event bus, code

Aggiungere Contenitori

Per ogni contenitore:

  1. Clicca "+" e seleziona "Aggiungi Contenitore"
  2. Inserisci:
    • Nome: "Applicazione Web", "Server API", "PostgreSQL"
    • Descrizione: La sua responsabilità
    • Tecnologia: "React", "Node.js", "PostgreSQL 15"

Collegare i Contenitori

Mostra come i contenitori comunicano:

  • App Web → Server API: "Effettua chiamate API [REST/HTTPS]"
  • Server API → Database: "Legge/scrive dati [SQL]"
  • Server API → Cache: "Memorizza dati di sessione [protocollo Redis]"

Passo 5: Aggiungere Componenti (Opzionale)

Per i contenitori critici, entra nei componenti:

  1. Fai doppio clic su un contenitore
  2. Aggiungi componenti che rappresentano i moduli principali:
    • Controller
    • Servizi
    • Repository
    • Utility

Passo 6: Usare la Scoperta IA (Opzionale)

Lascia che l'IA ti aiuti a documentare l'architettura:

Collegare il Repository

  1. Vai su Impostazioni Progetto → Repository
  2. Collega il tuo provider Git
  3. Seleziona il tuo repository

Eseguire la Scoperta

  1. Clicca "Avvia Scoperta"
  2. Attendi il completamento dell'analisi
  3. Rivedi le scoperte in sospeso

Revisione e Approvazione

  1. Controlla ogni elemento scoperto
  2. Modifica nomi/descrizioni se necessario
  3. Approva gli elementi accurati
  4. Rifiuta o modifica quelli non corretti

Passo 7: Aggiungere Documentazione

Descrizioni degli Elementi

Clicca su qualsiasi elemento e aggiungi descrizioni dettagliate:

  • Scopo e responsabilità
  • Decisioni chiave prese
  • Note importanti

Registri delle Decisioni Architetturali

Documenta le decisioni importanti:

  1. Vai alla sezione ADR
  2. Clicca "Nuovo ADR"
  3. Compila:
    • Titolo: "Usare PostgreSQL per la persistenza"
    • Contesto: Perché questa decisione era necessaria
    • Decisione: Cosa è stato deciso
    • Conseguenze: Impatto della decisione

Collegare la Documentazione

Collega ADR e documenti a elementi specifici per fornire contesto.

Passo 8: Condividere con il Team

Invitare Membri del Team

  1. Vai su Impostazioni Progetto → Team
  2. Clicca "Invita"
  3. Inserisci gli indirizzi email
  4. Assegna i ruoli (Visualizzatore, Editor, Amministratore)

Creare Link di Condivisione

Per gli stakeholder senza account:

  1. Clicca "Condividi" nella barra degli strumenti
  2. Configura le opzioni di accesso
  3. Copia e condividi il link

Esportare Diagrammi

Per presentazioni o documenti:

  1. Clicca "Esporta"
  2. Scegli il formato (PNG, SVG, PDF)
  3. Scarica i tuoi diagrammi

Best Practice

Inizia in Modo Semplice

  • Comincia con il Contesto del Sistema
  • Aggiungi dettagli progressivamente
  • Non cercare di documentare tutto in una volta

Mantieni Aggiornato

  • Aggiorna quando l'architettura cambia
  • Esegui la scoperta IA dopo cambiamenti importanti
  • Rivedi regolarmente con il team

Concentrati sulla Comunicazione

  • Usa nomi chiari e descrittivi
  • Aggiungi contesto nelle descrizioni
  • Mostra le relazioni più importanti

Prossimi Passi

Congratulazioni! Hai creato la tua prima documentazione architetturale. Continua ad apprendere: