Acerca de arc42

arc42, La plantilla de documentación para arquitectura de sistemas y de software.

Por Dr. Gernot Starke, Dr. Peter Hruschka y otros contribuyentes.

Revisión de la plantilla: 7.0 ES (basada en asciidoc), Enero 2017

© Reconocemos que este documento utiliza material de la plantilla de arquitectura arc 42, http://www.arc42.de. Creada por Dr. Peter Hruschka y Dr. Gernot Starke.

La versión de esta plantilla contiene textos de ayuda y explicación Se utiliza para familiarizarse con arc42 y comprender sus conceptos. Para la documentación de su propio sistema puede utilizar la version plain.

1. Introducción y Metas

Describe los requerimientos relevantes y las directrices que los arquitectos de software y el equipo de desarrollo deben considerar. Entre estas se incluyen:

  • Objetivos empresariales subyacentes, características esenciales y requerimientos funcionales para el sistema

  • Metas de calidad para la arquitectura

  • Las partes interesadas pertinentes y sus expectativas

1.1. Vista de Requerimientos

Los requisitos para este proyecto se basan en crear un chat para poder hablar con diferentes personas, estilo WhatsApp o Facebok Messenger, con la diferencia que las conversaciones y otros datos estarán descentralizados. Esto signfica que nuestros datos ya no estarán en los servidores de la aplicación y solo nosotros y a quien demos autorización podrán acceder a nuestros datos.

1.2. Metas de Calidad

Meta Descripción

Seguridad y privacidad

Esto es algo básico, ya que si un chat no tiene una buena seguridad ni asegura la privacidad del usuario, los mensajes que envies y tu información puede ser accesible para otras personas.

Usabilidad

Queremos que el chat sea utilizado por gente acostumbrada a este tipo de aplicaciones y que para la gente que no los suela utilizar, le sea fácil aprender como funciona y sea capaz de utilizarlo

Responsiveness(Responder ante una acción)

Un chat que tarde mucho tiempo en enviar y recibir mensajes no tendría mucho sentido, por ello nosotros queremos que esta aplicación responda antes un cambio, una acción, o simplemente el envío de un mensaje rápidamente

1.3. Partes interesadas (Stakeholders)

Rol/Nombre Contacto Expectativas

Equipo de desarrollo

Mediante reuniones en las que organizamos el trabajo personal y un control de versiones, en este caso GitHub

Conseguir desarrollar un producto funcional y que siga las necesidades y demandas del cliente

Profesor

Hará un seguimiento del desarrollo del proyecto durante los laboratorios, donde también podemos preguntarle dudas. Para la revisión de las versiones definitivas del proyecto, observará como ha ido el desarrollo mediante GitHub, es decir, revisará lo que ha hecho cada uno

Ser un punto de apoyo al equipo de desarrollo, para que este consiga implementar un producto funcional

Cliente(Solid)

Hay foros y charlas en las que ellos participan y en las que nosotros podemos consultar dudas, aprender de dudas que hayan tenido otros equipos de desarrollo y entender mejor cual es el producto final que quiere el cliente.

Obtener un producto funcional y que se adecue a los objetivos de calidad que ha establecido con el equipo de desarrollo al principio del proyecto

Usuarios

Cuando el producto este acabado, estos podrán valorarlo mediante diferentes canales de comunicación que llegarán a nosotros. Gracias a esto, ellos pueden detectar errores al usarlo que nos podrán notificar y que nosotros podremos corregir

Poder usar un producto final que funcione, que sea fácil de utilizar y que sea útil

2. Restricciones de la Arquitectura

Restricción Explicación

No usar lenguaje técnico

Es un chat para que lo pueda utilizar todas las personas sea cual sea su nivel en la tecnología teniendo, por supuesto, el mínimo conocimiento

Chat descentralizado

Debe ser un chat en donde cada usuario sea propietario de sus propios datos

Interfaz amigable y estética

Tiene que ser fácil de manejar por el usuario y agradable para la vista para que la persona que lo utilice se canse menos ya sea de la vista o cognitivamente

Segura y privada

Algo obvio pero de suma importancia comentar ya que los datos tendrán que estar descentralizados y no podrá nadie verlos

Documentación técnica

Se usará una documentación técnica como es Arc42 ya que es de las mejores para la documentación de arquitectura del software

Crear grupos de chat

Se deben poder comunicar entre los usuarios en grupos para que hablen a la vez siempre y cuando

Enviar fotos, vídeos u otro tipo de archivos

Los usuarios deben de poder enviarse entre sí cualquier tipo de archivo por el chat para e

Tener notificaciones

Se va a poder recibir notificaciones por mensajes recibidos a través del chat

3. Alcance y Contexto del Sistema

Table 1. Contenido

Socios de comunicacion

Entendimiento

Clientes

Interactuan de forma normal con la aplicacion de DeChat, conversando con otras personas, mandando imagenes etc.

DeChat

Una vez que el cliente envia un mensaje, imagen o similar, se iniciara una "comunicación" con el POD personal de ese cliente, siempre y cuando se haya concedido permiso a DeChat para acceder al POD, mediante la libreria "solid-auth-client", para guardar en ese POD el mensaje y posteriormente enviar un enlace al otro cliente, con el que se esta manteniendo una conversación, de ese mensaje que acaba de enviar concediendole permiso para ver SOLO ese mensaje. Pero siempre manteniendo ese mensaje en el POD personal del primer cliente, esto es lo que se consigue con descentralización. Sería también factible que alguno de los clientes tuviese varios POD y distribuyera los datos entre ellos en cualquier caso el funcionamiento seguiría siendo el mismo, solamente aumenta la descentralización.

POD

Son almacenes de datos personales en linea y va a estar alojado donde el usuario lo estime oportuno. Aqui es donde van a estar almacenados toda la informacion, mensajes, etc. Que haya comunicado el cliente con la aplicacion de DeChat. Su función principal será separar la aplicación y los datos.
Motivación

Las interfases de dominio y las interfases técnicas a los socios de comunicación son de los aspectos más críticos del sistema. Se debe asegurar el entendimiento de ellos.

Forma

  • Listas de socios de comunicación y sus interfases.

3.1. Contexto de Negocio

Contenido

En este diagrama de caja negra se muestra las interfases de dominio a los socios y como se va a realizar la comunicación entre las distintas entitades que van a formar la estructura basica de nuestra aplicacion de DeChat. No se explicará su funcionamiento interno, para ello se realizaran otros diagramas en siguientes apartados como el "Diagrama de caja blanca".

Diagrama de caja negra

Tambien se ha proporcionado una pequeña leyenda de este diagrama para facilitar su compresion en caso de que haya habido alguna duda.

Leyenda del diagrama de caja negra

Motivación

Todas las partes interesadas deben entender que datos son intercambiados con el ambiente del sistema.

Forma

He utilizado un diagrama de caja negra.

3.2. Contexto Técnico

Contenido

Las interfases técnicas (medios de transmisión y canales) enlanzando al sistema con su ambiente. De manera adicional el mapeo de las entradas/salidas específicas del dominio a los canales, es decir, una explicación acerca de que entrada/salida utiliza cual canal.

Motivación

Muchas partes relacionadas realizan decisiones arquitectónicas basadas en las interfases técnicas entre el sistema y su contexto. Especialmente los diseñadores de infraestructura o hardware deciden estas interfases técnicas.

Forma

Por ejemplo, diagramas UML de despligue describiendo los canales a sistemas vecinos, junto con una tabla de mapeo mostrando las relaciones entre los canales y las entradas/salidas.

<Diagrama o Tabla>

<Opcional: Explicación de las interfases técnicas>

<Mapeo de Entrada/Salida a canales>

4. Estrategia de solución

Contenido

Un resumen corto y explicación de las estrategias y decisiones fundamentales para la solución que le dan forma a la arquitectura del sistema. Estas incluyen:

  • Decisiones tecnológicas

  • Decisiones acerca de la descomposición a alto nivel de un sistema, por ejemplo, el uso de algún patrón de diseño o de arquitectura.

  • Decisiones en como alcanzar metas de calidad claves

  • Decisiones organizacionales relevantes, como el seleccionar un proceso de desarrollo o delegar ciertas tareas a terceros.

Motivación

Estas decisiones son las piedras angulares de la arquitectura. Son la base de muchas otras decisiones detalladas o reglas de implementación.

Forma

Realice la explicación de las deciciones clave de manera breve.

Justifique las decisiones y porque se realizaron de esa manera, basado en el planteamiento del problema, las metas de calidad y restricciones clave. Refierase a los detalles en las secciones posteriores.

5. Vista de Bloques

Contenido

La vista de bloques muestra la descomposición estática del sistema en bloques de construcción (módulos, componentes, subsistemas, clases, interfases, paquetes, bibliotecas, marcos de desarrollo, capas, particiones, funciones, macros, operaciones, estructuras de datos,…​) así como sus dependencias (relaciones, asociaciones,…​)

Esta vista es obligatoria para cualquier documentación de arquitectura. Es la analogía al plano de una casa.

Motivación

Mantener una visión general de su código fuente haciendo su estructura comprensible de manera abstracta.

Esto permite comunicar a las partes interesades en un nivel abstracto sin entrar en detalles de implementación.

Forma

La vista de bloques comprende una colección jerárquica de cajas negras y cajas blancas (ver figura de abajo) y sus descripciones.

Jerarquía de bloques de construcción

Nivel 1 comprende la descripción de Caja Blanca del sistema en general junto con las descripciones de Caja Negra de todos los bloques contenidos.

Nivel 2 hace zoom a los bloques de construcción del Nivel 1. Entonces contiene la descripción de Caja Blanca de los bloques de construcción selecionadas del nivel 1,junto con las descripciones de caja negra de sus bloques de construcción internas.

Nivel 3 Hace zoom a los bloques selectos del nivel 2, y así sucesivamente.

5.1. Sistema General de Caja Blanca

Vista general

Motivación

Este diagrama representa la vista más global del proyecto

Bloques de construcción contenidos
Nombre Responsabilidad

Persona

 Usuario usando el chat

POD

 Desc. en el glosario.

Dechat

Aplicación (chat)

5.2. Nivel 2

Aquí se especifica la estructura interna de (algunos) bloques de construcción del nivel 1 como cajas blancas.

Debe decidir cuales bloques de construcción del sistema son lo suficientemente importantes para justificar una descripción detallada. Prefiera la relevancia sobre la completitud. Especifique bloques de construcción importantes, sorprendentes, riesgosos, complejos o volátiles. Deje fuera las partes normales, simples, estándares o aburridas del sistema.

5.2.1. Caja Blanca <bloque de construcción 1>

…​Describe la estructura interna de bloque de construcción 1.

<plantilla de caja blanca>

5.2.2. Caja Blanca <bloque de construcción 2>

<plantilla de caja blanca>

…​

5.2.3. Caja Blanca <bloque de construcción m>

<plantilla de caja blanca>

5.3. Nivel 3

Aqui se especifica la estructura interna de (algunos) de los bloques de construcción del nivel 2 como cajas blancas.

Cuando la arquitectura requiera más niveles detallados copiar esta sección para niveles adicionales.

5.3.1. Caja Blanca <_bloque de construcción x.1_>

Especifica la estructura interna de bloque de construcción x.1.

<plantilla de caja blanca>

5.3.2. Caja Blanca <_bloque de construcción x.2_>

<plantilla de caja blanca>

5.3.3. Caja Blanca <_bloque de construcción y.1_>

<plantilla de caja blanca>

6. Vista de Ejecución

Contenido

La vista de ejecución describe el comportamiento concreto y la interacción de los bloques de construcción del sistema en forma de escenarios en las siguientes áreas:

  • Casos de uso o características importantes: ¿Cómo los ejecutan los bloques de construcción?

  • Interacciones en interfases externas críticas: ¿Cómo cooperan los bloques de construcción con los usuarios y sistemas vecinos?

  • Administración y operación: Carga, inicialización, detención.

  • Escenarios de error y excepción.

Observación: El criterio principal para la elección de los escenarios posibles (flujos de trabajo, secuencias) es su relevancia arquitectónica. No es importante describir un gran número de escenarios. Se debe documentar una selección representativa.

Motivación

Debe entenderse como las instancias de los bloques de construcción del sistema realizan su trabajo y se comunican en tiempo de ejecución. Deben capturarse principalmente los escenarios que comuniquen a las partes relacionadas que tengan problemas para comprender los modelos estáticos en la documentación (Vista de Bloques de Construcción, Vista de Despliegue).

Forma

Hay muchas notaciones para describir los escenarios, por ejemplo: * Lista numerada de pasos (en lenguaje natural). * Diagramas de flujo o de actividades * Diagramas de secuencia * BPMN o EPCs (Cadenas de procesos de eventos) * Máquinas de estado * …​.

6.1. <Escenario de ejecución 1>

  • <Inserte un diagrama de ejecución o la descripción del escenario>

  • <Inserte la descripción de aspectos notables de las interacciones entre los bloques de construcción mostrados en este diagrama.>

6.2. <Escenario de ejecución 2>

6.3. …​

6.4. <Escenario de ejecución n>

7. Vista de Despliegue

Contenido

La vista de despliegue describe:

  1. La infraestructura técnica usada para ejecutar el sistema, con elementos de infraestructura como locaciones geográficas, ambientes, computadoras, procesadores, canales y topologías de red así como otros elementos de infraestructura.

  2. El mapeo de los bloques de construcción (software) en dichos elementos de infraestructura.

Comúnmente los sistemas son ejecutados en diferentes ambientes, por ejemplo, ambiente de desarrollo, de pruebas, de producción. En dichos casos deberían documentarse todos los ambientes relevantes.

Deberá documentarse la vista de despliegue de manera especial cuando el software se ejecute como un sistema distribuido con mas de una computadora, procesador, servidor o contenedor o cuando se diseñen los procesadores y chips de hardware propios.

Desde una perspectiva de software es suficiente con capturar los elementos de la infraestructura necesarios para mostrar el despliegue de los bloques de construcción. Los arquitectos de hardware pueden ir más alla y describir la infraestructura a cualquier nivel de detalle que requieran.

Motivación

El software no corre sin haardware. El hardware subyacente puede influenciar el sistema o algunos conceptos entrecruzados. Por ende, es necesario conocer la infraestructura.

Forma

Quizá el más alto nivel de diagrama de despliegue esté contenido en la sección 3.2. como contexto técnico con la propia infraestructura como UNA caja negra. En esta sección se deberá realizar un acercamiento a ésta caja negra utilizando diagramas de despliegue adicionales:

  • UML provee diagramas de despliegue para expresar la vista. Uselos, probablemente con diagramas anidados.

  • Cuando las partes relacionadas de Hardware prefieran otro tipo de diagramas además de los diagramas de despliegue, permítales usar cualquier tipo que permita mostrar los nodos y canales de la infraestructura.

7.1. Nivel de infraestructura 1

Describa (Usualmente en una combinación de diagramas, tablas y texto):

  • La distribución del sistema en múltiples ubicaciones, ambientes, computadoras, procesadores, …​ así como las conexiones físicas entre ellos

  • La motivación o justificación de importancia para la estructura de despliegue

  • Características de Calidad y/o rendimiento de la infraestructura

  • El mapeo de los artefactos de software a los elementos de la infraestructura.

Para múltiples ambientes o despliegues alternativos copie esta sección para todos los ambientes relevantes.

<Diagrama General>

Motivación

<Explicación en forma textual>

Características de Calidad/Rendimiento

<Explicación en forma textual>

Mapeo de los Bloques de Construcción a Infraestructura

<Descripción del mapeo>

7.2. Nivel de Infraestructura 2

Aquí puede incluir la estructura interna de (algunos) elementos de infraestructura del nivel 1.

Copie la estructura del nivel 1 para cada elemento elegido.

7.2.1. <Elemento de Infraestructura 1>

<diagrama + explicación>

7.2.2. <Elemento de Infraestructura 2>

<diagrama + explicación>

…​

7.2.3. <Elemento de Infraestructura n>

<diagrama + explicación>

8. Conceptos Transversales (Cross-cutting)

Contenido

Esta sección describe de manera general, las principales ideas de solución y regulación que son relevantes en multiples partes (→ cross-cutting/transversales) del sistema. Dichos conceptos están relacionados usualmente a múltiples bloques de construcción. Pueden incluir diversos temas, tales como:

  • Modelos de dominio

  • Patrones de arquitectura o patrones de diseño

  • Reglas de uso para alguna tecnología específica.

  • Decisiones técnicas principales o generales

  • Reglas de implementación

Motivación

Conceptos que forman la base para la integridad conceptual (consistencia, homogeneidad) de la arquitectura. Entonces, son una contribución importante para alcanzar la calidad interna del sistema.

Algunos de estos conceptos no pueden ser asignados a bloques de construcción individuales (por ejemplo seguridad). Este es el lugar en la plantilla provisto para una especificación cohesiva de dichos conceptos.

Forma

La forma puede ser variada:

  • Papeles conceptuales con cualquier tipo de estructura

  • Modelo transversal (cross-cutting) de fragmentos o escenarios usando notación de las vistas arquitectónicas

  • Implementaciones de muestra, especialmente para conceptos técnicos.

  • Referencias a uso típico en frameworks estándar (por ejemplo, el uso de Hibernate para mapeo Objeto/Relacional) The form can be varied:

Estructura

La estructura potencial (pero no obligatoria) para esta sección podría ser:

  • Conceptos de dominio

  • Conceptos de experiencia de usuario (UX)

  • Conceptos de seguridad

  • Patrones de diseño y arquitectura * A potential (but not mandatory) structure for this section could be:

  • Domain concepts

  • User Experience concepts (UX)

  • Safety and security concepts

  • Architecture and design patterns

  • "Bajo el capó"

  • Conceptos de desarrollo

  • Conceptos de operación

Nota: Puede ser difícil asignar conceptos individuales a un tema específico de la lista

Posibles temas para conceptos transversales

8.1. <Concepto 1>

<explicación>

8.2. <Concepto 2>

<explicación>

…​

8.3. <Concepto n>

<explicación>

9. Decisiones de Diseño

Contenido

Decisiones arquitectónicas importantes, costosas, a larga escala o riesgosas incluyendo sus razonamientos. Con "Decisiones" nos referimos a la elección de una alternativa basada en cierto criterio.

Se debe usar el juicio para decidir si una decisión arquitectónica debe ser documentada en esta sección central o si sería preferible documentarla localmente (Por ejemplo, dentro de una plantilla de caja blanca de un bloque de construcción).

Evite la redundancia. Tomar de referencia la sección 4, donde ya se capturaron las decisiones más importantes para la arquitectura.

Motivación

Las partes relacionadas del sistema deben comprender y trazar las decisiones.

Forma

Varias opciones:

  • Lista o tabla, ordenada por importancia y consecuencias o:

  • Mayor detalle en secciones separadas por cada sección.

  • Registro de Decisiones de Arquitectura (ADR por sus siglas en inglés) para cada decisión importante.

10. Requerimientos de Calidad

Contenido

Esta sección describe todos los requerimientos de calidad como un árbol de calidad con escenarios. Los más importantes ya han sido descritos en la sección 1.2 (Metas de Calidad).

Aquí se capturan los requerimientos de calidad con menor prioridad, que no crearán altos riesgos en caso de que no sean cubiertos con totalidad.

Motivación

Dado que los requerimientos de calidad tendrán mucha influencia en las decisiones arquitectónicas deben tomarse en cuenta los elementos importantes para las partes relacionadas que sean concretas y medibles.

10.1. Árbol de Calidad

Contenido

El árbol de calidad (Definido en ATAM - Método de análisis de compensación de arquitectura por sus silas en inglés) con escenarios de calidad/evaluación como hojas.

Motivación

La estructura de árbol con prioridades provee un vistazo general para un gran número de requerimientos de calidad.

Forma

El árbol de calidad es un vistazo a alto nivel de las metas de calidad y requerimientos:

  • Un refinamiento del término de "calidad" a manera de árbol. Utilice "calidad" o "utilidad" como raíz.

  • Un mapa mental con categorías de calidad como ramas principales

En cualquier caso incluya ligas a los escenarios de las siguientes secciones.

10.2. Escenarios de calidad

Contenido

Concretización de requerimientos de calidad (que pueden ser vagos o implícitos) utilizando escenarios de calidad.

Estos escenarios describen lo que debería pasar cuando un estímulo llega al sistema.

Para los arquitectos, son importantes dos tipos de escenarios:

  • Escenarios de uso (también llamados escenarios de aplicación o escenarios de caso de uso), que describen la reacción en tiempo de ejecución de un sistema a un determinado estímulo. Esto incluye también escenarios que describen la eficiencia o el rendimiento del sistema. Por ejemplo: El sistema reacciona a la petición de un usuario en un segundo.

  • Escenarios de cambios, describen la modificación del sistema a su ambiente inmediato. Por ejemplo: Cuando se implementa funcionalidad adicional o requerimietnos para el cambio de un atributo de calidad.

Motivación

Los escenarios crean requerimientos de calidad concretos y permiten medirlos de manera mas sencilla o decidir si han sido cumplidos.

Cuando se requiere evaluar la arquitectura utilizando métodos como ATAM se necesitan describir las metas de calidad (de la sección 1.2) de manera más precisa hasta un nivel de escenarios que pueden ser discutidos y evaluados.

Forma

Texto en forma libre o tabular.

11. Riesgos y deuda técnica

Riesgo

Explicación

Suspender la asignatura

El riesgo más importante que corremos es el de suspender la asignatura por lo que tendremos que esforzarnos para trabajar y superar la asignatura

Primera vez en un proyecto version web

Hemos trabajado anteriormente en proyectos web de sencilla complejidad y tendremos que buscar más información sobre como trabajan este tipo de páginas

Nada experiencia con Solid

No habíamos oido hablar nunca de ello y tendremos que mirar todo tipo de proyectos que lo hayan usado ya sea para utilizar algunos componentes o para aprender

Poca experiencia con Angular

Al realizar pocos trabajos web, herramientas como Angular no las hemos tocado y por lo que tendremos que buscar más información sobre ello para trabajar

Seguridad web

No hemos trabajado nunca en temas de seguridad y menos en páginas web, habrá que estudiar sobre ello

Poca experiencia en proyectos en grupo

Trabajamos junto a otros compañeros pocas veces y, además, nos conocemos poco por lo que la comunicación al principio va a ser importante para compenetrarnos más adelante mejor

No hay mucho tiempo

Al tener que compaginar esta asignatura con otras de tercero iremos algo apretados de tiempo por lo que tocará trabajar

No suficiente experiencia con github

Algunos integrantes no tienen experiencia con github pero otro integrantes les pueden ayudar

12. Glosario

Término Definición

Responsiveness

En español no encontre una palabra que defina correctamente esta meta, pero su traducción quiere decir que, en este caso el chat, responda ante una acción o que sea sensible a ella

POD

POD simula ser una base de datos personal en la que cada uno guarda sus datos y para que las aplicaciones accedan a estos datos, debe ser el propietario del POD el que les de permiso. Puedes ser propietario de este POD o usar uno que proporcione alguna compañia.