Conceptos Fundamentales
Esta página explica los conceptos clave que encontrarás al usar Archyl.
Proyectos
Un Proyecto es el contenedor de nivel superior para tu documentación de arquitectura. Cada proyecto representa un sistema de software o producto que deseas documentar.
Los proyectos contienen:
- Diagramas de arquitectura (Sistemas, Contenedores, Componentes, Código)
- Relaciones entre elementos
- Documentación y ADRs
- Flujos de usuario
- Configuración y acceso del equipo
Elementos
Los elementos son los bloques de construcción de tus diagramas de arquitectura:
Sistemas
Un Sistema representa un sistema de software - el nivel más alto de abstracción. En el modelo C4, esto es lo que estás documentando.
- Sistemas Internos: Sistemas que posees y mantienes
- Sistemas Externos: Sistemas de terceros con los que interactúas (APIs, productos SaaS)
Contenedores
Un Contenedor es una unidad desplegable/ejecutable por separado que ejecuta código o almacena datos:
- Aplicaciones web
- Aplicaciones móviles
- Servidores API
- Bases de datos
- Colas de mensajes
- Sistemas de archivos
Componentes
Un Componente es una agrupación de funcionalidad relacionada dentro de un contenedor:
- Controladores
- Servicios
- Repositorios
- Módulos
Elementos de Código
El Código representa el nivel más bajo - construcciones de código reales:
- Clases
- Interfaces
- Funciones
- Módulos
Relaciones
Las Relaciones muestran cómo los elementos se comunican o dependen entre sí. Incluyen:
- Una etiqueta describiendo la interacción (ej: "Lee de", "Envía eventos a")
- Información opcional de tecnología (ej: "REST/HTTPS", "gRPC", "AMQP")
- Dirección mostrando el flujo
Overlays
Los Overlays son agrupaciones visuales que ayudan a organizar tus diagramas sin cambiar la estructura subyacente. Úsalos para:
- Agrupar elementos relacionados
- Resaltar áreas específicas
- Crear límites visuales
Niveles
Archyl usa los cuatro niveles de abstracción del modelo C4:
| Nivel | Muestra | Audiencia |
|---|---|---|
| Contexto del Sistema | Tu sistema en su entorno | Todos |
| Contenedor | Bloques técnicos de alto nivel | Personas técnicas |
| Componente | Estructura de componentes dentro de contenedores | Desarrolladores |
| Código | Detalles a nivel de código | Desarrolladores |
Organizaciones y Equipos
Organizaciones
Una Organización es el espacio de trabajo de tu cuenta. Contiene:
- Todos tus proyectos
- Miembros del equipo
- Información de facturación
- Configuración
Equipos
Los Equipos ayudan a organizar el acceso a proyectos:
- Agrupa miembros del equipo por departamento, proyecto o responsabilidad
- Controla el acceso a proyectos específicos
- Gestiona permisos a nivel de equipo
Roles
Archyl tiene tres roles:
| Rol | Puede Ver | Puede Editar | Puede Administrar |
|---|---|---|---|
| Visor | Sí | No | No |
| Editor | Sí | Sí | No |
| Admin | Sí | Sí | Sí |
Descubrimiento IA
El Descubrimiento IA es el proceso de analizar automáticamente tu código fuente para descubrir elementos de arquitectura. Este:
- Se conecta a tu repositorio Git
- Analiza la estructura y patrones del código
- Identifica sistemas, contenedores y componentes
- Crea relaciones entre elementos
- Genera sugerencias de documentación
ADRs
Los Architecture Decision Records (ADRs) documentan decisiones de arquitectura importantes:
- Qué se decidió
- Por qué se decidió
- Qué alternativas se consideraron
- Cuáles son las consecuencias
Flujos
Los Flujos de Usuario documentan cómo los usuarios o datos se mueven a través de tu sistema:
- Secuencias paso a paso
- Enlaces a elementos de arquitectura
- Diagramas de flujo visuales