Mappa di proprietà - Archyl Docs

Visualizza la proprietà di team e utenti nell'architettura con bolle interattive, linee di dipendenza e monitoraggio della copertura

Mappa di proprietà

La Mappa di proprietà offre una visione d'insieme di chi possiede cosa nell'intera architettura. Team e utenti appaiono come bolle interattive, dimensionate in base al numero di elementi che possiedono. Passa il cursore per rivelare le linee di dipendenza tra i proprietari e fai clic per esplorare in dettaglio gli elementi di cui ogni team o persona è responsabile.

Concetti fondamentali

Proprietari

Ogni elemento C4 (system, container, component) può essere assegnato a uno o più proprietari:

Tipo di proprietario Descrizione
Team Un team all'interno della tua organizzazione. Ideale per rappresentare squad, guild o team di dominio.
Utente Un singolo utente. Utile per maintainer individuali o per la responsabilità personale.

Un elemento può avere contemporaneamente sia proprietari di tipo team che di tipo utente. Gli elementi senza alcun proprietario sono tracciati come senza proprietario e contribuiscono alle lacune di copertura.

Copertura

La copertura misura quanti elementi dell'architettura hanno almeno un proprietario assegnato. L'intestazione della mappa di proprietà mostra:

  • Percentuale di copertura complessiva — colorata in verde (80%+), ambra (50-79%) o rosso (sotto il 50%)
  • Dettaglio per livello — statistiche separate per system, container e component
  • Conteggio posseduti / totali — numeri grezzi per un riferimento rapido

Dipendenze

Quando esistono relazioni C4 tra elementi posseduti da team diversi, la mappa di proprietà traccia linee di dipendenza tra quei proprietari. Questo evidenzia l'accoppiamento tra team — ad esempio, "i servizi del team Frontend dipendono dall'API Gateway del team Platform."

Le dipendenze sono:

  • Aggregate dalle singole relazioni C4 in archi proprietario-proprietario
  • Pesate in base al numero di relazioni sottostanti (più spessa = più dipendenze)
  • Mostrate al passaggio del cursore per mantenere la panoramica pulita

Utilizzo della Mappa di proprietà

Panoramica

Naviga su Global Architecture → scheda Ownership. La panoramica mostra tutti i team e gli utenti come bolle colorate:

  • Dimensione della bolla riflette quanti elementi il proprietario gestisce
  • Colore della bolla è assegnato automaticamente per ogni team/utente
  • Icona del team/utente o avatar è visualizzata all'interno di ogni bolla, se disponibile

Le bolle sono posizionate tramite un layout force-directed che raggruppa naturalmente i proprietari connessi più vicini tra loro.

Passaggio del cursore

Passa il cursore su una qualsiasi bolla per:

  1. Vedere un tooltip con il nome completo del proprietario e il conteggio degli elementi
  2. Rivelare le linee di dipendenza verso i proprietari connessi (con tratteggi animati e badge con conteggio)
  3. Attenuare le bolle non correlate in modo che il vicinato di proprietà risalti

Zoom nel dettaglio

Fai clic su una qualsiasi bolla per ingrandire la vista dettagliata degli elementi di quel proprietario:

  1. Un'animazione di rivelazione circolare effettua la transizione dalla bolla a un pannello dettagli a schermo intero
  2. L'intestazione hero mostra l'icona del proprietario, il nome, il tipo (Team/Utente) e le schede statistiche
  3. Le schede statistiche fungono da filtri — fai clic su "Systems", "Containers" o "Components" per mostrare solo quel tipo
  4. Gli elementi sono visualizzati in una griglia di card raggruppata per livello C4, con:
    • Nome e descrizione dell'elemento
    • Nome del progetto
    • Pill di co-proprietà (altri team/utenti che possiedono anch'essi questo elemento)
  5. Premi Escape o fai clic su Back per tornare alla panoramica

Ricerca

La barra di ricerca filtra a livello di bolla. Digita qualsiasi combinazione di:

  • Nome del proprietario — es. "Platform" o "Alice"
  • Nome dell'elemento — es. "API Gateway"
  • Nome del progetto — es. "Payment Service"

La ricerca utilizza il fulltext matching: tutti i termini devono comparire nel nome del proprietario della bolla, nei nomi degli elementi o nei nomi dei progetti.

Elementi senza proprietario

Fai clic sul toggle unowned nell'intestazione per rivelare una bolla grigia speciale contenente tutti gli elementi senza alcun proprietario. Questo aiuta a identificare le lacune di copertura che richiedono attenzione.

Assegnazione della proprietà

Tramite il diagramma

  1. Fai clic destro su qualsiasi system, container o component nel diagramma C4
  2. Apri la sezione Owners nel pannello dei dettagli
  3. Fai clic su Add Owner e seleziona un team o un utente
  4. La mappa di proprietà si aggiorna automaticamente

Tramite la vista dettagliata della Mappa di proprietà

Quando sei nella vista ingrandita di un team o utente, gli elementi elencati mostrano la loro proprietà attuale. Naviga sull'elemento nel diagramma del suo progetto per modificare i proprietari.

Tramite API

Usa gli endpoint dei proprietari degli elementi per assegnare la proprietà in modo programmatico:

Impostare i proprietari del team:

PUT /api/v1/c4/systems/:id/owners
Content-Type: application/json
Authorization: Bearer <token>

{
  "teamOwnerIds": ["<team-uuid-1>", "<team-uuid-2>"],
  "userOwnerIds": ["<user-uuid-1>"]
}

Lo stesso schema di endpoint funziona per i container (/c4/containers/:id/owners) e i component (/c4/components/:id/owners).

Buone pratiche

Assegnare la proprietà fin da subito

  • Imposta la proprietà del team quando crei o scopri nuovi system
  • Includi la proprietà nel processo di revisione dell'AI discovery
  • Punta a una copertura dell'80%+ su tutti i livelli C4

Preferire i team ai singoli utenti

  • I team sopravvivono al turnover dei dipendenti — la proprietà individuale crea silos di conoscenza
  • Assegna i team come proprietari principali e aggiungi singoli utenti per la responsabilità quando necessario
  • Mappa i team sulla struttura reale di squad o domini della tua organizzazione

Verificare le dipendenze tra team

  • Passa periodicamente il cursore su ogni team per controllare le linee di dipendenza
  • Un alto numero di dipendenze tra due team può indicare un accoppiamento stretto
  • Usa queste informazioni per orientare le decisioni sui confini dei servizi e il lavoro sui contratti API

Monitorare la copertura nel tempo

  • Controlla la percentuale di copertura nell'intestazione
  • Affronta gli elementi senza proprietario prima che si accumulino
  • Considera la copertura di proprietà al 100% come un obiettivo di igiene, non un'attività una tantum

Prossimi passi