Créer Votre Premier Projet
Ce guide complet vous accompagne dans la création de votre premier projet de documentation d'architecture dans Archyl, de la configuration initiale au partage avec votre équipe.
Prérequis
Avant de commencer :
- Un compte Archyl (inscrivez-vous ici)
- Un système logiciel que vous voulez documenter
- Optionnellement : Accès au dépôt de votre base de code
Étape 1 : Créer un Nouveau Projet
Depuis le Tableau de Bord
- Connectez-vous à Archyl
- Cliquez sur le bouton "+ Nouveau Projet"
- Entrez les détails de votre projet :
- Nom : Un nom clair et descriptif (ex : "Plateforme E-commerce")
- Description : Aperçu bref du système
- Tags : Mots-clés pour l'organisation (ex : "backend", "microservices")
- Cliquez sur "Créer le Projet"
Paramètres du Projet
Après la création, configurez votre projet :
- Visibilité : Public ou privé
- Accès équipe : Quelles équipes peuvent voir/modifier
- Dépôt : Connecter pour la découverte IA (optionnel)
Étape 2 : Comprendre le Contexte du Système
Avant de dessiner des diagrammes, comprenez le contexte de votre système :
Identifier les Utilisateurs
Qui utilise votre système ?
- Utilisateurs finaux (clients, employés)
- Administrateurs
- Développeurs externes
- Autres systèmes
Identifier les Systèmes Externes
Avec quoi votre système interagit-il ?
- Processeurs de paiement
- Fournisseurs d'authentification
- Services d'email/notification
- Plateformes d'analytics
- APIs partenaires
Étape 3 : Créer le Diagramme de Contexte Système
Ajouter Votre Système Principal
- Dans le canevas vide, cliquez sur "+" ou faites un clic droit
- Sélectionnez "Ajouter un Système"
- Entrez :
- Nom : Le nom de votre système
- Description : Ce qu'il fait
- Type : Interne (vous le possédez)
Ajouter les Utilisateurs
- Cliquez sur "+" et sélectionnez "Ajouter une Personne"
- Créez chaque type d'utilisateur :
- Nom : "Client", "Utilisateur Admin", etc.
- Description : Leur rôle et ce qu'ils font
Ajouter les Systèmes Externes
- Cliquez sur "+" et sélectionnez "Ajouter un Système Externe"
- Pour chaque dépendance externe :
- Nom : "Stripe", "SendGrid", etc.
- Description : Ce qu'il fournit
Créer les Relations
- Survolez l'élément source
- Glissez du point de connexion vers la cible
- Ajoutez un label : "Passe des commandes via", "Envoie des emails via", etc.
- Optionnellement ajoutez la technologie : "REST/HTTPS", "SMTP"
Étape 4 : Plonger dans les Conteneurs
Ouvrir la Vue Conteneur
Double-cliquez sur votre système principal pour zoomer au niveau Conteneur.
Identifier les Conteneurs
Quels sont les blocs de construction techniques ?
- Applications : App web, app mobile, client desktop
- Services : Serveur API, workers en arrière-plan
- Magasins de données : Bases de données, caches, stockage de fichiers
- Files de messages : Bus d'événements, queues
Ajouter les Conteneurs
Pour chaque conteneur :
- Cliquez sur "+" et sélectionnez "Ajouter un Conteneur"
- Entrez :
- Nom : "Application Web", "Serveur API", "PostgreSQL"
- Description : Sa responsabilité
- Technologie : "React", "Node.js", "PostgreSQL 15"
Connecter les Conteneurs
Montrez comment les conteneurs communiquent :
- App Web → Serveur API : "Fait des appels API [REST/HTTPS]"
- Serveur API → Base de Données : "Lit/écrit des données [SQL]"
- Serveur API → Cache : "Cache les données de session [protocole Redis]"
Étape 5 : Ajouter les Composants (Optionnel)
Pour les conteneurs critiques, zoomez dans les composants :
- Double-cliquez sur un conteneur
- Ajoutez les composants représentant les modules majeurs :
- Contrôleurs
- Services
- Repositories
- Utilitaires
Étape 6 : Utiliser la Découverte IA (Optionnel)
Laissez l'IA vous aider à documenter votre architecture :
Connecter le Dépôt
- Allez dans Paramètres du Projet → Dépôt
- Connectez votre fournisseur Git
- Sélectionnez votre dépôt
Lancer la Découverte
- Cliquez sur "Démarrer la Découverte"
- Attendez que l'analyse se termine
- Révisez les découvertes en attente
Réviser & Approuver
- Vérifiez chaque élément découvert
- Modifiez les noms/descriptions si nécessaire
- Approuvez les éléments précis
- Rejetez ou modifiez les incorrects
Étape 7 : Ajouter de la Documentation
Descriptions des Éléments
Cliquez sur n'importe quel élément et ajoutez des descriptions détaillées :
- But et responsabilités
- Décisions clés prises
- Notes importantes
Architecture Decision Records
Documentez les décisions importantes :
- Allez dans la section ADRs
- Cliquez sur "Nouvel ADR"
- Remplissez :
- Titre : "Utiliser PostgreSQL pour la persistance"
- Contexte : Pourquoi cette décision était nécessaire
- Décision : Ce qui a été décidé
- Conséquences : Impact de la décision
Lier la Documentation
Liez les ADRs et docs à des éléments spécifiques pour le contexte.
Étape 8 : Partager avec Votre Équipe
Inviter les Membres de l'Équipe
- Allez dans Paramètres du Projet → Équipe
- Cliquez sur "Inviter"
- Entrez les adresses email
- Assignez les rôles (Lecteur, Éditeur, Admin)
Créer des Liens de Partage
Pour les parties prenantes sans compte :
- Cliquez sur "Partager" dans la barre d'outils
- Configurez les options d'accès
- Copiez et partagez le lien
Exporter les Diagrammes
Pour les présentations ou documents :
- Cliquez sur "Exporter"
- Choisissez le format (PNG, SVG, PDF)
- Téléchargez vos diagrammes
Bonnes Pratiques
Commencez Simple
- Commencez par le Contexte Système
- Ajoutez du détail progressivement
- N'essayez pas de tout documenter d'un coup
Gardez À Jour
- Mettez à jour quand l'architecture change
- Lancez la découverte IA après des changements majeurs
- Révisez régulièrement avec votre équipe
Concentrez-vous sur la Communication
- Utilisez des noms clairs et descriptifs
- Ajoutez du contexte dans les descriptions
- Montrez les relations les plus importantes
Prochaines Étapes
Félicitations ! Vous avez créé votre première documentation d'architecture. Continuez à apprendre :