Creando Tu Primer Proyecto
Esta guía completa te acompaña en la creación de tu primer proyecto de documentación de arquitectura en Archyl, desde la configuración inicial hasta compartir con tu equipo.
Prerrequisitos
Antes de comenzar:
- Una cuenta de Archyl (regístrate aquí)
- Un sistema de software que quieras documentar
- Opcionalmente: Acceso al repositorio de tu código
Paso 1: Crear un Nuevo Proyecto
Desde el Panel de Control
- Inicia sesión en Archyl
- Haz clic en el botón "+ Nuevo Proyecto"
- Ingresa los detalles de tu proyecto:
- Nombre: Un nombre claro y descriptivo (ej: "Plataforma E-commerce")
- Descripción: Resumen breve del sistema
- Etiquetas: Palabras clave para organización (ej: "backend", "microservicios")
- Haz clic en "Crear Proyecto"
Configuración del Proyecto
Después de la creación, configura tu proyecto:
- Visibilidad: Público o privado
- Acceso del equipo: Qué equipos pueden ver/editar
- Repositorio: Conectar para descubrimiento IA (opcional)
Paso 2: Entender el Contexto del Sistema
Antes de dibujar diagramas, entiende el contexto de tu sistema:
Identificar Usuarios
¿Quién usa tu sistema?
- Usuarios finales (clientes, empleados)
- Administradores
- Desarrolladores externos
- Otros sistemas
Identificar Sistemas Externos
¿Con qué interactúa tu sistema?
- Procesadores de pagos
- Proveedores de autenticación
- Servicios de email/notificación
- Plataformas de analytics
- APIs de socios
Paso 3: Crear el Diagrama de Contexto del Sistema
Agregar Tu Sistema Principal
- En el lienzo vacío, haz clic en "+" o clic derecho
- Selecciona "Agregar Sistema"
- Ingresa:
- Nombre: El nombre de tu sistema
- Descripción: Qué hace
- Tipo: Interno (lo posees)
Agregar Usuarios
- Haz clic en "+" y selecciona "Agregar Persona"
- Crea cada tipo de usuario:
- Nombre: "Cliente", "Usuario Admin", etc.
- Descripción: Su rol y qué hacen
Agregar Sistemas Externos
- Haz clic en "+" y selecciona "Agregar Sistema Externo"
- Para cada dependencia externa:
- Nombre: "Stripe", "SendGrid", etc.
- Descripción: Qué proporciona
Crear Relaciones
- Pasa el cursor sobre el elemento origen
- Arrastra desde el punto de conexión al objetivo
- Agrega una etiqueta: "Realiza pedidos vía", "Envía emails a través de", etc.
- Opcionalmente agrega tecnología: "REST/HTTPS", "SMTP"
Paso 4: Profundizar en Contenedores
Abrir la Vista de Contenedor
Haz doble clic en tu sistema principal para hacer zoom al nivel de Contenedor.
Identificar Contenedores
¿Cuáles son los bloques de construcción técnicos?
- Aplicaciones: App web, app móvil, cliente de escritorio
- Servicios: Servidor API, workers en segundo plano
- Almacenes de datos: Bases de datos, cachés, almacenamiento de archivos
- Colas de mensajes: Buses de eventos, colas
Agregar Contenedores
Para cada contenedor:
- Haz clic en "+" y selecciona "Agregar Contenedor"
- Ingresa:
- Nombre: "Aplicación Web", "Servidor API", "PostgreSQL"
- Descripción: Su responsabilidad
- Tecnología: "React", "Node.js", "PostgreSQL 15"
Conectar Contenedores
Muestra cómo se comunican los contenedores:
- App Web → Servidor API: "Hace llamadas API [REST/HTTPS]"
- Servidor API → Base de Datos: "Lee/escribe datos [SQL]"
- Servidor API → Caché: "Cachea datos de sesión [protocolo Redis]"
Paso 5: Agregar Componentes (Opcional)
Para contenedores críticos, haz zoom en componentes:
- Haz doble clic en un contenedor
- Agrega componentes que representen módulos principales:
- Controladores
- Servicios
- Repositorios
- Utilidades
Paso 6: Usar Descubrimiento IA (Opcional)
Deja que la IA te ayude a documentar tu arquitectura:
Conectar Repositorio
- Ve a Configuración del Proyecto → Repositorio
- Conecta tu proveedor Git
- Selecciona tu repositorio
Ejecutar Descubrimiento
- Haz clic en "Iniciar Descubrimiento"
- Espera a que el análisis termine
- Revisa descubrimientos pendientes
Revisar y Aprobar
- Verifica cada elemento descubierto
- Edita nombres/descripciones si es necesario
- Aprueba elementos precisos
- Rechaza o modifica los incorrectos
Paso 7: Agregar Documentación
Descripciones de Elementos
Haz clic en cualquier elemento y agrega descripciones detalladas:
- Propósito y responsabilidades
- Decisiones clave tomadas
- Notas importantes
Architecture Decision Records
Documenta decisiones importantes:
- Ve a la sección ADRs
- Haz clic en "Nuevo ADR"
- Completa:
- Título: "Usar PostgreSQL para persistencia"
- Contexto: Por qué esta decisión era necesaria
- Decisión: Qué se decidió
- Consecuencias: Impacto de la decisión
Enlazar Documentación
Enlaza ADRs y docs a elementos específicos para contexto.
Paso 8: Compartir con Tu Equipo
Invitar Miembros del Equipo
- Ve a Configuración del Proyecto → Equipo
- Haz clic en "Invitar"
- Ingresa direcciones de email
- Asigna roles (Visor, Editor, Admin)
Crear Enlaces de Compartir
Para partes interesadas sin cuenta:
- Haz clic en "Compartir" en la barra de herramientas
- Configura opciones de acceso
- Copia y comparte el enlace
Exportar Diagramas
Para presentaciones o documentos:
- Haz clic en "Exportar"
- Elige formato (PNG, SVG, PDF)
- Descarga tus diagramas
Mejores Prácticas
Comienza Simple
- Comienza con Contexto del Sistema
- Agrega detalle progresivamente
- No intentes documentar todo de una vez
Mantenlo Actualizado
- Actualiza cuando la arquitectura cambie
- Ejecuta descubrimiento IA después de cambios importantes
- Revisa regularmente con tu equipo
Enfócate en la Comunicación
- Usa nombres claros y descriptivos
- Agrega contexto en descripciones
- Muestra las relaciones más importantes
Próximos Pasos
¡Felicidades! Has creado tu primera documentación de arquitectura. Continúa aprendiendo: