3. Documents d'arquitectura

Els DAs són els elements principals de l’aplicació, i tot el sistema gira al seu voltant. Un DA està format pel seu propi contingut, però també per altres informacions com són:

• Nom: Es genera automàticament a partir del nom de l’aplicació.
• Tipus d’arquitectura: És el que canvia la plantilla a omplir. Es selecciona durant la seva creació. Però es pot canviar.
• Versió: S’assigna automàticament a mesura que el DA avança pels diferents estats.
• Estat: Indica en quina etapa del projecte està el DA. Més endavant existeix una secció amb més informació sobre el cicle d’estats.
• Nom de l’usuari que el va crear.

Creació d’un DA

Per crear un DA, primer cal seleccionar una aplicació de la llista principal. Tal com s’ha esmentat anteriorment, només es pot crear un únic DA per aplicació. Per tant, si una aplicació ja en conté un, no serà possible crear-ne un altre.

En el costat esquerre d’aquesta mateixa pantalla, es pot visualitzar la informació sobre l’aplicació. Si l’aplicació no té cap DA, es pot crear-ne un prement el botó “Afegir nou” situat a la part superior dreta de la pantalla.

En fer-ho, apareixerà una finestra emergent on caldrà introduir:

• Tipus d’arquitectura: Que és un selector per seleccionar una o més arquitectures aplicables.
• Nom de la plantilla: El nom del DA. S’omple automàticament a partir del nom de l’app. Tots dos camps són obligatoris. En prémer el botó “Desa”, es crearà el DA buit. La plantilla per omplir es genera dinàmicament segons les arquitectures seleccionades.

Edició d’un DA

Aquesta és la pantalla per omplir els DAs, la funcionalitat clau de tota l’aplicació, i la funció principal dels arquitectes.

Ara s’explicaran els elements principals de la pantalla.

• Finestra d’informació: S’ubica a la part superior esquerra i conté informació relativa al DA, concretament:
  • Nom del DA (camp editable).
  • Versió.
  • Estat.
  • Valoració en estrelles: Indica la qualitat del DA segons diferents mètriques, per més informació existeix una secció.
  • Llistat d’arquitectures seleccionades (camp editable)
• Botons canvi d’estat: Entre la finestra d’informació i el botó de tornar, serveix per avançar en el cicle de desenvolupament del DA.
• Botó per tornar: Per tornar a la pantalla d’una aplicació.
• Índex de vistes: Conjunt de desplegables per navegar entre les diverses vistes. Cadascuna d’elles té un color associat que indica si són vistes requerides i el seu estat de completitud.
• Zona principal: On es troben les seccions a omplir. Quan s’accedeix a un DA, cap secció està oberta per defecte; per obrir-ne una, cal fer clic sobre el seu nom a l’índex.

El codi de colors que es segueix en l’índex és el següent:

• Vermell: Secció requerida que encara no s’ha començat a omplir.
• Groc: Secció requerida parcialment omplerta.
• Verd: Secció requerida completament omplerta.
• Gris: Secció opcional o no aplicable. Aquests colors canvien dinàmicament en funció de l’estat d’edició de la vista.

Quan es clica sobre una secció, apareix el formulari corresponent, format per caixes de text, taules i caselles de selecció. Per completar una secció requerida, cal omplir com a mínim tots els camps marcats amb un ‘*’.

Les taules i les caixes de text no es poden editar directament des d’aquesta pantalla. Per fer-ho, cal prémer “Edita registre” o “Edita taula”, ubicats al costat de cada apartat, per obrir un pop-up i introduir les dades.

Les taules amb diferents apartats també inclouen el ‘*’ per cada secció que indica si es un camp requerit per omplir.

Plantilles d’arquitectura

La selecció de plantilles d’arquitectura determina les seccions que cal omplir en el DA. Per exemple, si s’escull SaaS, les seccions de Desenvolupament i Desplegament no seran necessàries, ja que es tracta d’una solució ja gestionada pel proveïdor.

La selecció d’arquitectures es realitza inicialment durant la creació d’un DA, però també es pot modificar durant l’edició. Per fer-ho, cal fer clic al botó d’edició situat a la part superior esquerra, al costat de les arquitectures seleccionades. Un cop desats els canvis, les seccions s’actualitzen automàticament, modificant el seu estat a requerida, opcional o no aplicable. És important destacar que el conjunt de seccions visibles es manté inalterat; només s’afegiran o s’ocultaran els camps corresponents. A més, el canvi de plantilla no elimina la informació ja introduïda en els camps prèviament omplerts.

Si la selecció d’arquitectures provoca que una secció sigui requerida per un dels subconjunts, però no aplicable per un altre, es donarà prioritat a la restricció més estricta i la secció es marcarà com a requerida.

Com es pot veure a la imatge, aquest apartat no és aplicable per SaaS, però com que sí que ho és per almenys una altra arquitectura, es marca com requerit en l’índex amb el color vermell. Les arquitectures disponibles són:

• Cloud Privat.
• Cloud Public.
• Low Code.
• On Premise.
• Power Platform Suite.
• SaaS.
• Sharepoint.

Ara breument s’explicaran les arquitectures disponibles amb les seves particularitats i aspectes a tenir en compte:

Cloud Privat

Infraestructura allotjada en un núvol privat, gestionat per l’empresa o per un proveïdor, amb més control sobre seguretat i configuració. No hi ha cap vista que no apliqui per aquesta arquitectura, alguna de les seves particularitats són:

• Vista desplegament: Per cada entorn que apliqui s’haurà d’emplenar una taula.
• Hi ha una regla per facilitar l’ompliment del DA, i és que la informació de l’entorn Producció, es copia línia per línia a l’entorn Preproducció.

Cloud Public

Infraestructura allotjada en un núvol públic (AWS, Azure, Google Cloud, IBM Cloud…), amb escalabilitat i manteniment a càrrec del proveïdor. No hi ha cap vista que no apliqui per aquesta arquitectura, alguna de les seves particularitats són:

• És l’única arquitectura on cal afegir els costos del cloud en format calculadora.
• Només s’ha de seleccionar l’entorn i carregar el fitxer de la calculadora en format .xlsx o .csv.
• L’aplicació detectarà automàticament el tipus de proveïdor cloud i mostrarà el cost total mensual a partir de les dades del document.

Low code

Plataformes de desenvolupament amb mínim codi (com per exemple OutSystems), que permeten crear aplicacions ràpidament mitjançant interfícies visuals i components predefinits. Les vistes que no apliquen i que, per tant, no es poden omplir són:

• Desenvolupament
• Operacional

On premise

Aplicació allotjada en servidors físics dins de l’organització, amb total control sobre la infraestructura i seguretat. No hi ha cap vista que no apliqui per aquesta arquitectura, alguna de les seves particularitats són:

• Vista desplegament: Per cada entorn que apliqui s’haurà d’emplenar una taula.
• Hi ha una regla per facilitar l’ompliment del DA, i és que la informació de l’entorn Producció, es copia línia per línia a l’entorn Preproducció.

Power Platform Suite

Ecosistema de Microsoft que inclou Power Apps, Power Automate, Power BI i Power Virtual Agents per a automatització i desenvolupament ràpid d’aplicacions empresarials. Les vistes que no apliquen i que, per tant, no es poden omplir són:

• Desenvolupament
• Operacional

SaaS

Aplicacions accessibles via internet sense necessitat d’instal·lació local, com Office 365 o Google Workspace. Les vistes que no apliquen i que, per tant, no es poden omplir són:

• Desenvolupament
• Desplegament
• Operacional

Sharepoint

Plataforma de Microsoft per a gestió documental, col·laboració i creació d’intranets empresarials. Les vistes que no apliquen i que, per tant, no es poden omplir són:

• Desenvolupament
• Operacional

Estats d’un DA

Els DA passen per diferents estats abans d’arribar a producció. En aquest camí de validacions i revisions intervenen diferents rols (arquitecte, validador, ISOL) que tenen tasques específiques i úniques que només poden fer gràcies a pertànyer a aquell rol específic. Aquest és un diagrama que mostra el flux d’estats dels DAs:

Els estats són:

• Esborrany (draft): És el primer estat d’un nou DA. Durant aquest estat, l’arquitecte està omplint totes les seccions requerides; l’únic rol que intervé és l’arquitecte. Una vegada omple el DA, el publica fent clic al botó groc de dalt a la dreta.
• Publicat (Published): L’arquitecte afegeix un validador i el mou a l’estat “En validació”.
• Vegetatiu: Aquest no és un estat d’un DA sinó que és un subtipus. És aquell DA que ja ha estat en servei i durant l’estat d’Esborrany només s’incrementa la quantitat de recursos que necessita. En aquest cas, quan es publiqui passarà directament a l’estat “Validat”.
• En validació (Validating): El validador, juntament amb observadors, valida el DA i, per tant, passa a “Validat”. Si, per contra, vol que es corregeixin alguns apartats, afegirà uns comentaris (a la pròpia web) i el mourà a l’estat “En revisió”.
• En revisió (In revision): L’arquitecte canvia les parts que ha indicat el validador mitjançant comentaris. Una vegada considera que ha aplicat correctament els canvis, ho torna a posar a “En validació”. S’incrementa automàticament la versió menor en 1 (per exemple, de 1.2 a 1.3). Aquesta seqüència d’estats és un bucle, no es passa a l’estat “Validat” a no ser que el validador ho consideri convenient.
• Validat (Validated): És quan el validador considera que el DA és correcte. Es passa a “En projecte” en el moment de començar el desenvolupament.
• En projecte (Pre-prod): Si durant el desenvolupament es vol canviar alguna cosa del DA, l’ISOL el passaria de nou a l’estat “En revisió”. Una vegada finalitzat el desenvolupament, es passa a “En servei” (Production).
• En servei (Production): L’aplicació està correctament en producció. Si es vol fer algun canvi, es pot tornar el DA a l’estat “Esborrany”, incrementant la versió major en 1 (per exemple, de v1.2 a 2.0).
• Arxivat (Archived): Es tracta d’un estat dels DA que no forma part del flux habitual, ja que correspon a un tipus de DA independent. Inclou tots aquells DA antics que encara no han estat digitalitzats dins l’aplicació. Aquests DA no es poden consultar ni editar mentre no estiguin digitalitzats. Per digitalitzar-los, cal prémer el botó “Genera DA”. A partir de l’arquitectura seleccionada, amb IA s’omple automàticament la plantilla corresponent. Aquest procés dura un dia, ja que la digitalització es un procés que s’executa durant la nit. Un cop finalitzat, es genera un DA amb diverses seccions completades gràcies a la IA, tot i que cal revisar-les per possibles al·lucinacions. Tot i això, el procés suposa un estalvi significatiu de feina. També es disposa d’un botó per descarregar el DA en format PDF.
  • En cas d’error de la digitalització: Si la digitalització fa fallat recomanem que es torni a intentar la digitalització, utilitzant el botó de retry.
  • En cas que existeixi l’aplicació però no el DA en estat arxivat: En aquest cas significa que en el moment de fer la càrrega dels DAs en format PDF, aquest no existia en el conjunt i cal pujar-ho. Crear tiquet a Atom amb la informació de l’aplicació, i adjuntar el DA en format PDF.

Condicions DA vegetatiu

Un diagrama es considera vegetatiu només en situacions molt específiques. La primera condició és que el DA hagi estat, com a mínim, una vegada En servei, és a dir, que tingui una versió major a 1. El concepte de vegetatiu implica que es mantenen tots els elements de l’aplicació excepte aquells recursos que són estrictament necessaris. Per tant, durant l’estat Esborrany, només es poden modificar certs valors concrets. Que un DA sigui vegetatiu implica que, en publicar-lo des de l’estat Esborrany, passarà directament a Validat sense passar per En validació. Aquest canvi és fàcil de detectar, però per fer-ho encara més clar, quan un DA sigui vegetatiu es mostrarà una icona al costat del seu nom.

A més, només els DAs que inclouen almenys una d’aquestes plantilles: Cloud Privat, Cloud Public o On-Premises poden ser considerats vegetatius. Com que els requisits varien segons l’arquitectura, els detallem a continuació.

Cloud Privat

Durant l’estat Esborrany, l’arquitecte només pot modificar els següents paràmetres de la vista Desplegament:

• Contenidors (Memòria RAM, CPU, Disc persistent).
• Elements de catàleg cloud (Talla i Recursos addicionals).
• Emmagatzematge (Mida i Tier). Es pot modificar un o diversos d’aquests paràmetres, però si s’edita qualsevol altra secció, s’afegeix una nova línia o es modifica alguna imatge, el DA ja no podrà ser considerat vegetatiu, encara que s’hagin canviat alguns dels paràmetres mencionats.

Cloud Public

Durant l’estat Esborrany, l’arquitecte només pot modificar els següents paràmetres de la vista Desplegament:

• Preu de les calculadores Es pot modificar un o diversos d’aquests paràmetres, però si s’edita qualsevol altra secció, s’afegeix una nova línia o es modifica alguna imatge, el DA ja no podrà ser considerat vegetatiu, encara que s’hagin canviat el preu de les calculadores.

On-premises

Durant l’estat Esborrany, l’arquitecte només pot modificar els següents paràmetres de la vista Desplegament:

• Elements de catàleg cloud (Talla i Recursos addicionals)
• Emmagatzematge (Mida i Tier) Es pot modificar un o diversos d’aquests paràmetres, però si s’edita qualsevol altra secció, s’afegeix una nova línia o es modifica alguna imatge, el DA ja no podrà ser considerat vegetatiu, encara que s’hagin canviat alguns dels paràmetres mencionats.

Generar PDF

Un cop el DA s’ha completat i passa a l’estat Publicat, el PDF es genera automàticament. Aquest document inclou tota la informació introduïda a l’aplicació web, com ara taules, blocs de text, checkboxes, diagrames i imatges. Cada subversió té el seu propi PDF, que es pot descarregar des de la pantalla d’una aplicació concreta, fent clic a la icona de la lupa del DA.

Completar DA

En les següents subseccions s’expliquen els canvis entre estats els quals es requerida l’acció de l’arquitecte.

De Esborrany a Publicat

Per publicar un DA en estat Esborrany, cal completar totes les vistes requerides, fent que els elements de l’índex canviïn de vermell o groc a verd. Això s’aconsegueix omplint totes les seccions marcades amb un asterisc (*). Si s’intenta publicar un DA sense haver completat totes les vistes requerides, l’acció no serà possible i es mostrarà un missatge d’error. A més, apareixerà un botó (‘!’) en la finestra d’informació que si es clica obre un menú per visualitzar les vistes pendents de completar.

D’En revisió a En validació

L’objectiu d’aquest estat és revisar tots els comentaris introduïts pel validador i els observadors. Les vistes que contenen comentaris es marquen a l’índex i, quan s’obren, si hi ha comentaris, apareix un botó a la part superior dreta. En clicar-lo, es poden llegir tots els comentaris associats a aquella vista. Un cop l’arquitecte ha resolt tots els problemes identificats pel validador, ha de clicar el botó "En validació" per canviar d’estat. En el popup que apareixerà, es mostrarà automàticament un quadre resumint totes les seccions on s’han realitzat canvis (és a dir, on s’ha fet clic al botó "Desa" en alguna subsecció). A més, la versió menor s’incrementarà automàticament (per exemple, de v1.0 a v1.1). Si, en aquesta nova iteració de l’estat “En revisió”, el validador dona el seu vistiplau, el DA passarà automàticament a l’estat “Validat”.

Detalls transversals plantilles

En aquesta secció s’explicarà en més detall de quina manera omplir les seccions, regles creuades, i informació que cal conèixer.

Omplir seccions

Per omplir les seccions, cal fer-ho des del popup que s’obre en clicar a:

• Editeu registre: Permet escriure en un bloc de text amb opcions de personalització, com alineacions, llistats, etc.
• Editeu taula: Permet editar una taula amb diferents elements interactius, com blocs de text, checkboxes, selectors, etc.
• Afegeix línia: Permet afegir una nova línia a una taula de manera dinàmica.

En cas de dubtes sobre com omplir certes subseccions, es pot fer servir el botó d’informació (‘i’), situat al costat del títol de la subsecció. A més, en alguns casos específics, també hi ha botons d’informació en camps o apartats concrets per aclarir punts específics.

Qualitat DA

La qualitat del DA és una propietat informativa que s’avalua en una escala d’1 a 5 estrelles. És una forma ràpida d’informar al validador de la qualitat del DA, però no és un paràmetre definitiu ni decissiu. Aquesta avaluació es fa tenint en compte diferents parts avaluables, i la puntuació final del DA serà la nota mínima obtinguda de totes aquestes parts. Els punts que es tenen en compte per a l’avaluació són:

• Vista context → Detall de la iteració entre el sistema / solució i els sistemes externs: Depenent de l’Estil integració.
• Vista de desenvolupament → Tecnologies i llibreries introduïdes: Depenent de la versió introduïda comparant-la amb la del full de ruta. Utilitza IA per fer l’avaluació.
• Seguretat → Mesures i eines de seguretat: Depenent del Sistema d’autenticació.
• Disponibilitat → Afectació per la indisponiblitat d’entitats externes: Per obtenir 5 estrelles emplenar totes les files de la taula afegint la justificació.

Generar diagrama

La generació de diagrames de forma automàtica es pot fer en dos vistes diferents, en la de Context i en la de Fluxos de comunicació. Ara explicarem cadascuna d’elles i com afecta l’edició del DA en els canvis de la imatge generada:

Diagrama Context

Aquest diagrama vol representar la relació de l’aplicació amb les entitats externes, indicant la seva interacció, localització i/o autenticació. Per tant, la informació de totes tres taules de la vista de context són necessàries per la generació del diagrama. El diagrama és generat amb IA que interpreta el contingut de les taules i el genera. A continuació un exemple d’un diagrama generat.

Diagrama Fluxos de comunicació

Aquest diagrama varia en funció de la selecció realitzada a les dues taules anteriors. Hi ha cinc paràmetres que en determinen el diagrama: si cadascun d’ells està marcat, s’afegirà una o diverses relacions entre components en el diagrama generat. A continuació, es mostra un exemple de diagrama amb tots els paràmetres marcats com a “Sí”, és a dir, incloent-hi totes les connexions possibles.

Tal com s’ha esmentat, només hi ha cinc seleccions que modifiquen el diagrama. Per facilitar-ne la comprensió, s’ha assignat un nom clau a cadascun d’ells:

Correspondència entre seleccions i connexions al diagrama

• usuariInternet → Fletxa verda: des de SubxarxaA, passant per WAAP Net0 i FW PUB Net0, fins a Internet.User.
• usuaricointernet → Fletxa verda: des de SubxarxaA, passant per WAAP Net0 i FW PUB Net0, fins a Nus.User.
• usuaricointranet → Fletxa verd intens: des de Nus.User fins a SubxarxaA.
• Internet → Fletxa groga: entre SubxarxaA i Internet, passant per FW PUB Net0.
• intranet o cpdcointranet → Fletxa blava: entre SubxarxaB i CPDs, passant per PROXY Net0.

La resta de valors disponibles a les taules, tot i ser rellevants per al DA, no afecten la generació del diagrama.

Regles creuades

A continuació es detallaran algunes de les regles creuades de l’aplicació que cal conèixer:

• Vista Context
  • Detall de la iteració entre el sistema/solució i els sistemes externs: S’ha de crear com a mínim un registre per cada un dels sistemes descrits a la taula anterior, ja sigui com a origen o com a destí.
  • Diagrama: Abans de poder generar el diagrama amb IA, cal omplir les taules de la vista corresponent.
• Fluxos de Comunicació
  • Diagrama: Abans de generar el diagrama amb IA, s’ha de completar la informació a les taules de la vista.
• Vista Informació
  • Noves entitats a afegir: Si es selecciona “Sí”, cal afegir almenys una nova entitat a la taula.
  • Informació relativa a xarxes i dominis DNS de les publicacions corporatives
    • Informació de dominis DNS: El domini DNS ha de finalitzar amb “.gencat.cat”.
• Vista Desplegament (Cloud Privat & On Premise)
  • Taules d’instàncies i emmagatzematge:
    • Si s’omple la informació a l’entorn de producció, aquesta s’omple automàticament també a l’entorn de preproducció.
    • Si s’indica el “Nombre de Pods/Contenidors” per algun entorn o capa, en la vista de disponibilitat (Detalls de la disponibilitat), no es pot indicar un RTO (Recovery Time Objective) de 2 hores o viceversa.
    • Per tenir un RTO de 2 hores, s’han d’assignar almenys 2 contenidors.
• Informació relativa a l’aprovisionament d’ Infraestructura
  • Les taules que apareixen són les mateixes que les de la vista Desplegament.
  • L’únic que es pot indicar és si es tracta d’un nou desplegament.