docs: review of design chapter

Author: giacomoaccursi

docs/02-design/applicationLayer.md

@@ -10,9 +10,9 @@ has_children: false
 
 L'Application layer, contenente la business logic e tutti i casi d'uso del sistema, è stato progettato attraverso un'**architettura a microservizi event-driven**.
 
-La scelta dell'architettura a microservizi parte dalla volontà di ridurre la complessità suddividendo il dominio del problema attraverso modelli più piccoli che siano più facilmente gestibili e che, confinando i cambiamenti, siano più manutenibili, evitino l'ambiguità e rispettino il principio SRP (Single responsibility principle). I microservizi hanno il vantaggio, rispetto a una soluzione con un monolite, di poter adottare, per ogni microservizio, lo stack tecnologico desiderato. Infatti si parla di *Polyglot governance*, per le tecnologie, *Polyglot modelling*, per i modelli concettuali e *Polyglot persistence*, per le decisioni relative alla persistenza. Inoltre, ognuno di essi viene progettato, implementato e versionato autonomamente rendendo possibile il deploy e lo scaling di essi in modo indipendente.
+La scelta dell'architettura a microservizi parte dalla volontà di ridurre la complessità suddividendo il dominio del problema attraverso modelli più piccoli che siano più facilmente gestibili e che, confinando i cambiamenti, siano più manutenibili, evitino l'ambiguità e rispettino il principio SRP (Single responsibility principle). I microservizi hanno il vantaggio rispetto a una soluzione con un monolite di poter adottare per ogni microservizio lo stack tecnologico desiderato. Infatti si parla di *Polyglot governance* per le tecnologie, *Polyglot modelling* per i modelli concettuali e *Polyglot persistence* per le decisioni relative alla persistenza. Inoltre, ognuno di essi viene progettato, implementato e versionato autonomamente rendendo possibile il deploy e lo scaling di essi in modo indipendente.
 
-Per la progettazione dell'architettura sono state seguite le best-practices definite dal *DDD* partendo dalla definizione dei diversi *Bounded Context* e dalle loro relazioni all'interno della Context Map.
+Per la progettazione dell'architettura sono state seguite le best-practices definite dal *DDD* partendo dalla definizione dei diversi *Bounded Context* e dalle loro relazioni all'interno della *Context Map*.
 
 In <a href="#applicationLayerArchitecture">Figura 1</a> è possibile notare i microservizi sviluppati e le loro interazioni.
 
@@ -28,7 +28,7 @@ Sono stati individuati nove microservizi principali, uno per ciascun Bounded Con
 
 - *Building Management*: è il servizio che si occupa del monitoraggio del blocco operatorio e della sua gestione in termini di creazione e disposizione delle stanze e delle tecnologie mediche.
 - *Staff Tracking*: si occupa della memorizzazione della storia degli spostamenti dei professionisti sanitari all'interno del blocco operatorio. Sopra a questi dati abilita la possibilità di eseguire query più complesse in modo da ottenere, a partire dagli spostamenti, le informazioni desiderate.
-- *Automation Management*: è responsabile per tutte le automazioni all'interno del blocco operatorio. Nelle automazioni sono incluse sia quelle di gestione per l'ottimento di condizioni ambientali ottimali (temperatura, umidità, luminosità e standby mode) sia quelle relative alle automazioni che supportano i professionisti sanitari durante le loro operazioni (adattamento dell'ambiente con le migliori condizioni per l'utilizzo di una tecnologia medica) sia quelle richieste dal personale sanitario.
+- *Automation Management*: è responsabile per tutte le automazioni all'interno del blocco operatorio. Nelle automazioni sono incluse sia quelle di gestione per l'ottenimento di condizioni ambientali ottimali (temperatura, umidità, luminosità e standby mode) sia quelle relative alle automazioni che supportano i professionisti sanitari durante le loro operazioni (adattamento dell'ambiente con le migliori condizioni per l'utilizzo di una tecnologia medica) sia quelle richieste dal personale sanitario.
 - *Surgical Process Monitoring*: è il servizio che si occupa del monitoraggio dei processi chirurgici in corso all'interno del blocco operatorio raccogliendo tutti i dati necessari per rappresentare l'intervento associato.
 - *Surgery Report*: è il servizio che si occupa, a partire da tutti i dati raccolti dai vari microservizi, della generazione automatica del report dell'intervento. Inoltre prevede anche la possibilità, da parte di un professionista sanitario, di effettuare l'integrazione con parti aggiunte manualmente.
 - *User Management Integration*, *Patient Management Integration*, *Surgery Booking Integration* e *Medical Instrument Integration*: questi sono i servizi necessari per l'integrazione con i sistemi legacy presenti nella struttura ospedaliera. I servizi di integrazione indicati si occupano rispettivamente di: ottenere le informazioni rispetto ai professionisti sanitari, ottenere i dati anagrafici relativi ai pazienti, ottenere i dati relativi alle prenotazioni e alla calendarizzazione degli interventi chirurgici ed infine di integrarsi con i sistemi di telemetria per l'ottenimento dei parametri vitali dei pazienti.
@@ -37,14 +37,14 @@ Per quanto riguarda il bounded-context *Issue Management*, si è deciso di non p
 
 Si può notare la presenza di un *API Gateway* il quale ricopre il ruolo di entry point nel sistema per le chiamate di client esterni; nel nostro caso delle dashboard di blocco e di sala operatoria. La responsabilità di un API Gateway è quella di tradurre le richieste "client-friendly" effettuate al sistema dall'esterno nei protocolli utilizzati internamente all'architettura del sistema. L’API Gateway sviluppato implementa anche il pattern *API Composition* agendo da façade e semplificando l’accesso alle informazioni del sistema.
 
-Ogni microservizio - che necessita di mantenere dello stato - seguendo le best-practice, mantiene i dati privati, in un proprio database. I microservizi non devono avere database condivisi in quanto i dati devono essere scambiati tramite eventi o richieste esplicite. Per tutti i microservizi progettati è risultato particolare efficace l’utilizzo di database documentali, in particolare di [MongoDB](https://www.mongodb.com).
+Ogni microservizio che necessita di mantenere dello stato, seguendo le best-practice, mantiene i dati privati in un proprio database. I microservizi non devono avere database condivisi in quanto i dati devono essere scambiati tramite eventi o richieste esplicite. Per tutti i microservizi progettati è risultato particolarmente efficace l’utilizzo di database documentali, in particolare di [MongoDB](https://www.mongodb.com).
 
 Per quanto riguarda l'interazione tra microservizi, considerando la natura e i requisiti del sistema, si è scelto di adottare una comunicazione *event-driven* per tutto ciò che riguarda il flow del processo chirurgico e l'osservazione del Digital Twins layer.
 Tuttavia, l'approccio event-driven non è adatto all'interazione con i sistemi di integrazione e sopratutto alla maggior parte delle composizioni di API che l'API Gateway risolve. Perciò in questi casi si è optato per una comunicazione basata su richiesta-risposta sincrona one-to-one sfruttando *API REST*.
 
 Considerando la necessità di un *Event Broker* e non di un semplice *Message Broker* e le varie caratteristiche dei sistemi commerciali tra cui: il supporto della community, le funzionalità e i tool a disposizione è stato scelto *[Apache Kafka](https://kafka.apache.org)*.
 
-Tutti i microservizi sviluppati sono stati realizzati seguendo i principi della *Clean Architecture*, descritta in <a href="#cleanArchitecture">Figura 2</a> la quale ha permesso di separare correttamente la modellazione del dominio, i casi d’uso, la logica applicativa e tutto ciò che riguardava le tecnologie e l’infrastruttura, grazie al rispetto dei layers e della *dependency rule*. L’impiego di questa tipologia di architettura ha permesso di creare microservizi più facilmente testabili, estendibili e manutenibili.
+Tutti i microservizi sviluppati sono stati realizzati seguendo i principi della *Clean Architecture*, descritta in <a href="#cleanArchitecture">Figura 2</a> la quale ha permesso di separare correttamente la modellazione del dominio, i casi d’uso, la logica applicativa e tutto ciò che riguarda le tecnologie e l’infrastruttura, grazie al rispetto dei layers e della *dependency rule*. L’impiego di questi principi ha permesso di creare microservizi più facilmente testabili, estendibili e manutenibili.
 
 <div align="center">
 <img id="cleanArchitecture" src="imgs/cleanArchitecture.jpg" alt="Clean Architecture schema" width="80%">
@@ -57,7 +57,7 @@ Sono stati utilizzati i quattro layers descritti nell'[articolo](https://blog.cl
 - *Application layer*: contiene i *controller* e i *presenter*. I primi gestiscono l'orchestrazione del flusso dell'applicazione gestendo l'interazione tra gli attori esterni e le politiche di business definite nel core. Essi quindi non rappresentano concetti di dominio ne tanto meno definiscono regole di business. I secondi si occupano della serializzazione e della deserializzazione, quindi della presentazione, dei dati verso il layer infrastrutturale o il layer dei casi d'uso, adattando quindi i dati al formato più conveniente per i layer interessati.
 - *Infrastructure layer*: contiene tutte le scelte tecnologiche del sistema. Esse vengono confinate nel layer più esterno in quanto più volatili permettendo così a tutto ciò che viene definito nei layer più interni di rimanere valido anche a fronte di cambi tecnologici, assicurando maggiore flessibilità al sistema. 
 
-Nel caso in cui, i layer interni avessero bisogno, per far fronte alle proprie responsabilità, di interagire con astrazioni definite nei layer superiori, come definito nell'[articolo](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) sulla *Clean Architecture*, si sfrutta il principio *Dependency Inversion (DIP)* per far si che le dipendenze vadano solo verso l'interno. Ogniqualvolta si presentava il problema si è definita un'interfaccia nel layer interno che poi viene implementata nel layer esterno. In questo modo le dipendenze rimangono solamente verso l'interno, senza dipendere da concetti definiti nei layer esterni.
+Nel caso in cui i layer interni avessero bisogno di interagire con astrazioni definite nei layer superiori, come definito nell'[articolo](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) sulla *Clean Architecture*, si sfrutta il principio *Dependency Inversion (DIP)* per far si che le dipendenze vadano solo verso l'interno. Ogniqualvolta si è presentato il problema si è definita un'interfaccia nel layer interno che poi è stata implementata nel layer esterno. In questo modo le dipendenze rimangono solamente verso l'interno, senza dipendere da concetti definiti nei layer esterni.
 
 Al fine di agevolare l'implementazione del modello del dominio cercando di mappare i concetti all'interno del codice rispettando l'*Ubiquitous Language*, si è fatto uso di alcuni elementi del *design tattico* definiti all'interno del *Domain-Driven Design*. 
 

docs/02-design/digitalTwinsLayer.md

@@ -32,9 +32,9 @@ Lo stack *Azure* utilizzato e quindi l'architettura progettata è illustrata in
 
 Essa è composta da quattro servizi principali:
 
-- *Azure Digital Twins*: è un [servizio](https://azure.microsoft.com/it-it/products/digital-twins) *PaaS* che consente la creazione di grafi di *Digital Twins* basati su modelli scritti in *Digital Twins Definition Language* (DTDL). I modelli hanno un'espressività tale da permettere la modellazione di interi ambienti reali esprimendo tutte le proprietà e le relazioni in essere. Il grafo supporta l'aggiornamento di dati in real-time e quindi questo sarà il servizio richiamato dal Gateway di blocco al fine di eseguire lo shadowing. Inoltre, il servizio, come tutta la suite di Azure, è stato progettato con un'impronta event-driven. Questo fa si che tutti gli aggiornamenti del grafo si traducano in eventi che vengono distribuiti fuori dal servizio stesso pronti per essere raccolti ed elaborati.
+- *Azure Digital Twins*: è un [servizio](https://azure.microsoft.com/it-it/products/digital-twins) *Platform as a Service* (PaaS) che consente la creazione di grafi di *Digital Twins* basati su modelli scritti in *Digital Twins Definition Language* (DTDL). I modelli hanno un'espressività tale da permettere la modellazione di interi ambienti reali esprimendo tutte le proprietà e le relazioni in essere. Il grafo supporta l'aggiornamento di dati in real-time e quindi questo sarà il servizio richiamato dal Gateway di blocco al fine di eseguire lo shadowing. Inoltre, il servizio, come tutta la suite di Azure, è stato progettato con un'impronta event-driven. Questo fa si che tutti gli aggiornamenti del grafo si traducano in eventi che vengono distribuiti fuori dal servizio stesso pronti per essere raccolti ed elaborati.
 - *Azure Event Grid*: gli eventi emessi dal servizio *Azure Digital Twins* vengono spediti ad un endpoint. Come endpoint è stato scelto *[Azure Event Grid](https://azure.microsoft.com/en-us/products/event-grid)*, il quale è un servizio di Pub Sub messaging altamente scalabile che permette di costruire pipeline di dati integrando diversi servizi. Gli eventi così vengono raccolti da questo servizio e vengono rispediti lungo la pipeline progettata.
-- *Azure Function*: gli eventi raccolti vengono, prima di essere spediti, elaborati attraverso il servizio *[Azure Function](https://azure.microsoft.com/en-us/products/functions)*, il quale è una soluzione serverless *FaaS* che permette di specificare porzioni di codice con la possibilità di scaling automatico. Questo permette di specificare funzioni di mapping dei dati in modo agile all'interno di pipeline come quella descritta qui. Essa è necessaria per aumentare i dati degli eventi ed esprimerli  nel formato opportuno per il loro consumo.
+- *Azure Function*: gli eventi raccolti vengono, prima di essere spediti, elaborati attraverso il servizio *[Azure Function](https://azure.microsoft.com/en-us/products/functions)*, il quale è una soluzione serverless *Function as a Service* (FaaS) che permette di specificare porzioni di codice con la possibilità di scaling automatico. Questo permette di specificare funzioni di mapping dei dati in modo agile all'interno di pipeline come quella descritta qui. Essa è necessaria per aumentare i dati degli eventi ed esprimerli nel formato opportuno per il loro consumo.
 
 - *Azure SignalR*: gli eventi, una volta pronti, vengono resi disponibili all'Application Layer dell'architettura grazie al servizio *[Azure SignalR](https://azure.microsoft.com/it-it/products/signalr-service)*, il quale permette il push di aggiornamenti in tempo reale in modo completamente scalabile.