Concetti Fondamentali
Questa pagina spiega i concetti chiave che incontrerai usando Archyl.
Progetti
Un Progetto è il contenitore di livello superiore per la tua documentazione architetturale. Ogni progetto rappresenta un sistema software o prodotto che vuoi documentare.
I progetti contengono:
- Diagrammi architetturali (Sistemi, Contenitori, Componenti, Codice)
- Relazioni tra elementi
- Documentazione e ADR
- Flussi utente
- Impostazioni e accesso del team
Elementi
Gli elementi sono i blocchi fondamentali dei tuoi diagrammi architetturali:
Sistemi
Un Sistema rappresenta un sistema software — il livello più alto di astrazione. Nel modello C4, questo è ciò che stai documentando.
- Sistemi Interni: Sistemi che possiedi e mantieni
- Sistemi Esterni: Sistemi di terze parti con cui interagisci (API, prodotti SaaS)
Contenitori
Un Contenitore è un'unità distribuibile/eseguibile separatamente che esegue codice o memorizza dati:
- Applicazioni web
- App mobile
- Server API
- Database
- Code di messaggi
- File system
Componenti
Un Componente è un raggruppamento di funzionalità correlate all'interno di un contenitore:
- Controller
- Servizi
- Repository
- Moduli
Elementi di Codice
Il Codice rappresenta il livello più basso — costrutti di codice reali:
- Classi
- Interfacce
- Funzioni
- Moduli
Relazioni
Le Relazioni mostrano come gli elementi comunicano o dipendono l'uno dall'altro. Includono:
- Un'etichetta che descrive l'interazione (es. "Legge da", "Invia eventi a")
- Informazioni opzionali sulla tecnologia (es. "REST/HTTPS", "gRPC", "AMQP")
- Direzione che mostra il flusso
Overlay
Gli Overlay sono raggruppamenti visivi che aiutano a organizzare i diagrammi senza modificare la struttura sottostante. Usali per:
- Raggruppare elementi correlati
- Evidenziare aree specifiche
- Creare confini visivi
Livelli
Archyl utilizza i quattro livelli di astrazione del modello C4:
| Livello | Mostra | Pubblico |
|---|---|---|
| Contesto del Sistema | Il tuo sistema nel suo ambiente | Tutti |
| Contenitore | Blocchi tecnici ad alto livello | Persone tecniche |
| Componente | Struttura dei componenti nei contenitori | Sviluppatori |
| Codice | Dettagli a livello di codice | Sviluppatori |
Organizzazioni e Team
Organizzazioni
Un'Organizzazione è il workspace del tuo account. Contiene:
- Tutti i tuoi progetti
- Membri del team
- Informazioni di fatturazione
- Impostazioni
Team
I Team aiutano a organizzare l'accesso ai progetti:
- Raggruppa i membri per reparto, progetto o responsabilità
- Controlla l'accesso a progetti specifici
- Gestisci i permessi a livello di team
Ruoli
Archyl ha tre ruoli:
| Ruolo | Può Visualizzare | Può Modificare | Può Amministrare |
|---|---|---|---|
| Visualizzatore | Sì | No | No |
| Editor | Sì | Sì | No |
| Amministratore | Sì | Sì | Sì |
Scoperta IA
La Scoperta IA è il processo di analisi automatica della tua codebase per scoprire gli elementi architetturali. Essa:
- Si connette al tuo repository Git
- Analizza la struttura e i pattern del codice
- Identifica sistemi, contenitori e componenti
- Crea relazioni tra gli elementi
- Genera suggerimenti per la documentazione
ADR
I Registri delle Decisioni Architetturali (ADR) documentano le decisioni architetturali importanti:
- Cosa è stato deciso
- Perché è stato deciso
- Quali alternative sono state considerate
- Quali sono le conseguenze
Flussi
I Flussi Utente documentano come utenti o dati si muovono attraverso il sistema:
- Sequenze passo dopo passo
- Link agli elementi architetturali
- Diagrammi di flusso visivi