Tehniline arhitektuur

Alates 2018 neljandast kvartalist toimuvad E-ehituse platvormi edaspidi platvorm arendused, mis lähtuvad käesolevas dokumendis toodud nõuetest.

Käesolev dokument kajastab MKM IT-osakonna ja EHR arendajate poolt tehtud e-ehituse keskkonna arhitektuuri kokkuleppeid. Uutes arendustes tuleb järgida käesolevat dokumenti.

Juhul kui tekib vajadus käesolevas dokumendis toodud nõudeid laiendada või muuta, tuleb selleks eelnevalt saavutada kokkulepe MKM IT-spetsialistidega ning tehtud kokkulepped käesolevasse dokumenti sisse viia.

Arhitektuuri muutmise eesmärk

Tagada lõppkasutajatele kiire töökeskkond ja teenuste lühike vastuseaeg, et võimaldada head kasutajakogemust.
Muuta platvormi rakenduse edasiarendamine vähe ressursse nõudvaks, et tagada platvormi ajakohasus ning paindlikkus muudatuste sisseviimisel.
Tagada platvormi turvalisus ning platvormi komponentide pidev uuendamine, et vältida turvariske.
Tagada platvormi jätkusuutlikkus, võttes arendustes kasutusele järk järgult uusi tehnoloogiaid ja rakenduse käitluskeskkondi nii, et olemasolevaid rakendusi saaks töös hoida, kuni uued need välja vahetavad.
Tagada EHR vastavus kõikidele ISKE klassiga määratud nõuetele.

E-ehituse platvormi tarkvaralise arhitektuuri põhimõtted

Arhitektuur lähtub mikroteenuste kontseptsioonist,
ehk platvorm koosneb kesksest UI rakendusest ning sellega seotud API REST mikroteenuste rakendustest. (Mikroteenuse asemel on edaspidi kasutusel sõna teenus).
Vanem EHR Java Spring rakendust kasutatakse paralleelselt senikaua, kui uued teenused selle järk järgult välja vahetavad. Uute teenuste arendusel lähtume „Brownfield“ arendusmetoodikast,
ehk teenuste loomine lähtub olemas olevast tarkvarast kuni 2023 esimene kvartal. Peale seda võetakse vanem Java rakendus kasutusest maha.
E-ehituse platvormi tarkvaraline arhitektuur koosneb järgnevatest komponentidest (vt joonis 1):
- Kasutajaliidese rakendused (pakendatud konteinerrakendus)
- Pakendatud API konteinerrakendused
- Konteinerite käitluskeskkond Kubernetes koos Rancher haldustarkvaraga
- Andmebaasid
- Virtuaalserverid
- Riigipilv

Arhitektuur lähtub mikroteenuste kontseptsioonist,
ehk platvorm koosneb kesksest UI rakendusest ning sellega seotud API REST mikroteenuste rakendustest. (Mikroteenuse asemel on edaspidi kasutusel sõna teenus).
Vanem EHR Java Spring rakendust kasutatakse paralleelselt senikaua, kui uued teenused selle järk järgult välja vahetavad. Uute teenuste arendusel lähtume „Brownfield“ arendusmetoodikast,
ehk teenuste loomine lähtub olemas olevast tarkvarast kuni 2023 esimene kvartal. Peale seda võetakse vanem Java rakendus kasutusest maha.
E-ehituse platvormi tarkvaraline arhitektuur koosneb järgnevatest komponentidest (vt joonis 1):
- Kasutajaliidese rakendused (pakendatud konteinerrakendus)
- Pakendatud API konteinerrakendused
- Konteinerite käitluskeskkond Kubernetes koos Rancher haldustarkvaraga
- Andmebaasid
- Virtuaalserverid
- Riigipilv

Tasemetest detailsemalt

Kasutajaliides rakendused:
1. Kasutajaliides (User Interface) – lähtub microfrontend põhimõttest ehk kasutajaliides on jaotatud teenuste vahel komponentideks (custom elements).
2. Kõik kasutajaliidese komponendid kasutavad keskseid aluskomponente mida kasutatakse npm paketist ehr-components.
3. Kasutajaliidese loomisel kasutame React, HTML, CSS ja JavaScripti viimaseid versioone ning Nginx veebiserverit.
4. E-ehituse aluskomponendi loomisel ei tohi muuta esialgseid komponente. Esialgse komponendi alusel tuleb luua uus komponent ning lisada see e-ehituse komponentide projektis “src/ehr_components” folderisse. 
5. E-ehituse kasutajaliides käivitub juurkomponendist, mis asub projektis: ehr-ui ning kõik uued loodavad komponendid peavad olema integreeritud juurkomponenti.
6. E-ehituse aluskomponendi loomisel ei tohi muuta esialgseid komponente. Esialgse komponendi alusel tuleb luua uus komponent ning lisada see e-ehituse komponentide projektis “src/ehr_components” folderisse.
7. Juurkomponendis on komponentide infovahetuseks kasutusel Redux pakett.
8. Komponendid integreeritakse juurkomponenti npm paketina. Komponendi sisenditeks on “React props” ja väljunditeks “render props event”-d. Komponentide sisendid ja väljundid dokumenteeritakse React Styleguidist paketiga.
9. Kasutajaliidese juurkomponent integreeritakse olemasoleva Java rakendusega linkide kaudu, nii et EHR lingi avamisel käivitatakse juurkomponent ning sellest omakorda uue või vana Java rakenduse lehed (vt joonis 2).

Kasutajaliides rakendused:
1. Kasutajaliidese navigeerimiseks kasutame juurkomponendis react-router paketti
2. Kasutajaliidese stiilid võetakse juurkomponenti integreeritud e-ehituse CSS stiilifailist.
3. Kasutaliidese stiilide muutmiseks või lisamiseks on e-ehituse stiiliraamat. E-ehituse stiilifail koos stiiliraamatuga asub siin projektis. E-ehituse stiilifaili täiendamisel peab arendaja tagama, et muudatused ei kahjustaks olemasolevate komponentide töötamist. Peale muudatuste sisseviimist tuleb genereerida uus CSS ja integreerida see e-ehituse juurkomponenti.
4. Kasutaja õigused kasutajaliidese elementidele leitakse juurkomponendis või vajadusel alamkomponentides, kasutades e-ehituse JWT tokenit (vt. Kasutajaõiguste süsteemi detailanalüüs ja Juurdepääsu piirangud E-EHITUS platvormi teenustes ja kasutajaliideses.
5. Kasutajaliidese andmevahetuseks andmebaasiga kasutame REST teenustel põhinevat API-t.
6. Vormi väljade kohustuslikkuse kontrolli ja väljade kuvamise/ täitmise ärireeglid realiseerime võimalusel lehitsejas ja andmebaasi kirjutamisel vastavas API-s.
7. Kasutajaliidese põhivaated realiseeritakse prototüüpimisel kasutades e-ehituse aluskomponente.
8. E-ehituse kasutajaliides peab olema testitud enamlevinud lehitsejatega (Chrome, Edge, Firefox, Safari) ja mobiilivaates.
9. Kasutajaliides peab olema koostatud nii, et autoriseeritud kasutaja saaks muuta html elementide pealkirju, veateated ning abitekste.
10. Kasutajaliidese tekstid peavad asuma juurkomponendis keelefailides (eesti, inglise).
11. Lõppkasutajale kuvatavatel html elementidel peavad olema unikaalsed ID-d, et saaks rakendada kasutajaliidese automaattestimist.
12. Komponentidele luuakse staatiline html, et kuvada komponente ka juhul, kui javascript pole kättesaadav/lubatud.
13. Uute komponentide loomisel kasutame antd ja reacstrap pakette.
14. Kasutajaliidese loomisel kasutame create-react-app tööriistu (webpack, babel, eslint airbnb reeglitega).

Pakendatud API konteinerrakendused :
1. Uute API-de loomisel kasutatakse kas: Java, NodeJS või Python tehnoloogiate viimaseid stabiilseid versioone.
2. Uue API rakendusserverid käitatakse Docker konteinerites riigipilves Kubernetes klastris.
3. Kubernetes klastrite haldusvahendina kasutatakse Rancher tarkvara.
4. Uue API rakendused peavad sisaldama automaattarne: MKM Git -> Riigipilves Helm Chart vajalikke Helm konfiguratsiooni faile (vt. näiteks Helm konfiguratsioonifaile ja Helm kasutusjuhendit).
5. Automaattarne riigipilve lisatakse EHR Git-s projektidele, mis asuvad selles grupis.
6. Helm Charti abil peab saama paigaldada rakendused Rancher rakenduse kaudu e-ehituse test- ja toodangu klastris olevatesse: development, test, prelive, live projektides asuvatesse namespace-desse.
7. Olemasoleva Java rakenduse server (paikneb Tieto majutuses) jääb tööle, kuni olemasolev Java rakendus on kasutuselt maha võetud.
8. Olemasolev kaardiserver jääb eraldiseisva teenusena tööle, kuni luuakse uued kaarditeenused. Olemasolev kaardiserver kasutab Maa-ameti kaarditeenuseid.
9. Luuakse mikroteenuste kontseptsioonil baseeruv e-ehituse REST API. API kavandamiseks ja dokumenteerimiseks kasutatakse OpenAPI standardit ja Swagger tööriistu Swagger UI ja Swagger Editor. EHR API kavandamisel tuleb järgida EHR API kirjeldamise reegleid.
10. E-ehituse REST APIde kirjeldused asuvad siin. Uue API loomisel tuleb API kirjeldus lisada siia projekti (tulevikus siin)ning uus versioon tarnida riigipilve.
11. E-ehituse API loomisel tuleb tagada, et teenused ei korduks ja soovitav on olemasolevat teenust edasi arendada, mitte luua uusi teenuseid. Teenused peavad olema vähemalt 2 põhiversiooni (semver2 ) tagasiulatuvalt ühilduvad.
12. Andmete ülekandmiseks API-st kasutajaliidesesse kasutatakse võimalusel JSON formaati või eelneval kokkuleppel mõnda muud XML formaati (näiteks CityGML).
13. E-ehituse kaardikomponendist ja geo-otsingu teenustest andmete vahetuseks kasutatakse GeoJSON formaati.
14. Juhul, kui API teostab andmebaasis CRUD (
  Create, Read, Update, Delete) operatsioone siis andmete verifitseerimine toimub kahel tasemel ehk esmalt UI vormi kasutajaliideses ja seejärel enne andmebaasi viimist API rakenduses.
15. Teenuste autoriseerimine toimub vastavalt kasutajaõiguste süsteemi detailanalüüsile ja
  Juurdepääsu piirangud E-EHITUS platvormi teenustes ja kasutajaliideses.
16. Teenused, mis teostavad andmebaasidega CRUD operatsioone, tuleb luua nii, et transaktsioonid ning vajalikud Join operatsioonid toimuvad andmebaasis, kasutades andmebaasi protseduure, mitte API rakenduses.
17. Andmete terviklikkuse tagamiseks andmebaaside üleselt kasutatakse võimalusel (juhul, kui saga pattern realiseerimine pole otstarbekas) kahetasemelist “commit” lahendust (2PC) lisades transaktsiooni koordineerimist vajavate teenuste üleselt uue “commit” teenuse või vajadusel mikroteenustes nn. “Choreography-based saga pattern” metoodikat.
18. Teenuste ja andmebaasi ning teenuste omavaheliseks infovahetusel kasutatakse RabbitMQ Message Brokerit.

Andmebaas:
1. Mikroteenuste vajadusteks luuakse uued PostgreSQL andmebaasid vt. Ehitisregistri andmebaasid ja nende uuendamise juhend
2. Igal andmeobjektil on üks baas, kuhu andmed kirjutatakse. Juhul kui on vajadus kasutada andmeid mõnes teises baasis päringute teostamiseks siis luuakse teise baasi r prefiksiga view, mille abil andmeid saab lugeda. Andmete sünkroniseerimiseks andmebaaside vahel kasutatakse pglogical tarkvara.
3. Olemasolev Oracle ja uued baasid hoitakse sünkroonis RabbitMQ sõnumiedastusega, kuni olemasolev Java rakendus on kasutusel.
4. EHR unikaalvõtmete (EHR-kood, dokumendi number jm.) loomiseks kasutatakse koodide omistamise teenuseid.
5. Andmebaasi siseste operatsioonide teostamiseks luuakse SQL protseduurid, mida API-t realiseerivad komponendid välja kutsuvad.

Failisüsteem:
1. Konteinerakendustele on klastris kasutusel NFS block storage ja Longhorn block storage.
2. Klastrites on kasutusel S3 Object storage teenus, mis on eelistatud failide hoidmise lahendus.

Riigipilv:
1. Kõiki platvormi komponente käitatakse riigipilves
2. Platvormi jaoks on pilves loodud 2 privaatvõrku test ja toodang.
3. Arendajad saavad kasutada testvõrgus olevaid servereid ning Kubernetese klastrit.
4. Toodangu privaatvõrk, Kubernetese klaster ning virtuaalserverid on piiratud juurdepääsuga ainult administraatoritele.
5. Pilves olevate serveritega suhtlemiseks kasutatakse SSH lahendust gate.ehr.ee.
6. Rakenduste tarne pilve toimub git.ehr.ee vahendusel.
7. Pilve arhitektuuris kasutame nimelahendust (DNS). Vaata Eehitus DNS kirjeldus

Muud komponendid:
1. Cache jaoks on kasutusel Redis (Vaata). Redist saab rakendada vajadusel konteinerite vahel info jagamiseks või rakenduse andmete ajutiseks säilitamises kiires püsimälus.
2. Pilve arhitektuuris kasutame nimelahendust (DNS). Vt. e-ehitus DNS kirjeldus

Mikroteenuste rakendustele tuleb lisada Kubernetes liveness probe.
Uue teenuse loomisel kasutatakse võimalikult palju valmis arendatud komponente ja olemasolevaid raamistikke või teeke.
E-ehituse teenused peavad arenduse käigus olema kaetud unit testidega, mille abil kontrollitakse teenuse komponentide (alamosade) vigadeta tööd.
Javascripti kasutamisel (React, NodeJs) peab tarnitav kood olema kontrollitud Eslint Airbnb reelitega ning ei tohi sisaldada linteri veateateid.
Koodi kvaliteeti kontrollitakse CI/CD tarnetel Sonarqube tarkvaraga. Koodi Sonarqube raport peab olema:
1. Reliability Bug = 0
2. Security Vulnerability = 0
Rakenduse arendusel tuleb arvestada, et rakendus peab olema testitav Katalon automaattestidega ehk kasutajaliideses kasutatavad html elemendid peavad sisaldama unikaalset atribuuti näiteks id. Kasutajaliides peab olema testitud automaattestidega mobiilivaates ning toetatavate veebilehitsejate vaadetega. API peab olema testitud Katalon API testimiseks mõeldud testidega.
Rakenduste logid kogutakse kesksesse logihalduse teenusesse ja seetõttu peavad rakenduste logid olema Json formaadis. Logiteenuse kirjeldus

Üleminekuprotsessi etapid

Etapid on toodud ajalises järgnevuses, aga samas on võimalik etappe ka paralleelselt käivitada juhul, kui selleks on olemas piisavalt ressursse.

Tarkvaralise arhitektuuri dokumenteerimine
Olemasoleva EHR komponentideks jaotamine ja teenuste kavandamine (vt. järgmine ptk.)
Automaattarnete ja testide käivitamine
Teenuste kasutajaliidese arendamine (MTA UI + React)
Turvateenuste arendamine: JWT – ehk teenustele juurdepääsu pass, autoriseerimise süsteem ehk kasutajad/grupid/rollid/juurdepääsuõigused, andmete turvalisuse ja juurdepääsu muudatused.
Teenuste arendusprojektid, mille käigus arendatakse uus teenus ja muudetakse olemasolevat rakendust nii, et uue teenuse saab kasutusele võtta.

EHR olemasoleva rakenduse komponentideks jaotamine

Olemasoleva rakenduse teenusteks jaotamisel on aluseks EHR tänase rakenduse komponendid. Samuti tuleb komponentidena arvestada tänases EHR infrastruktuuris paiknevad eraldi rakendused:

andmeait,
EHR infoportaal,
VRM,
kaardirakendus.

Uue teenuse arendamisel tuleb järgida mikroteenuste põhimõtteid ehk teenuses peavad olema andmed, rakenduse server ja kasutajaliides nii, et EHR muude teenuste (va. elutähtsad teenused, mis on aluseks kõigi teiste teenuste toimimisele) katkestused ei mõjutaks ülejäänud teenuste tööd.

Kuna uute teenuste loomisel tuleb need integreerida olemasoleva rakendusega, siis tuleb olemasolevad EHR komponendid jaotada teenusteks arvestades olemasoleva rakenduse ülesehitust ja võimalusi nii, et uusi teenuseid saaks kasutusele võtta võimalikult vähe olemasolevat rakendust muutes. See võimaldab hoida kokku ressursse ning tagada lõppkasutajatele võimalikult sujuva ja probleemideta ülemineku protsessi.

E-ehituse tarneprotsess (tehnoloogia vaade)

E-ehituse teenuste tarkvaraline protsess on lahti kirjeldatud allpool oleval joonisel (vt. joonis 3).

Uue tarkvara tarnimisel võetakse kasutusele konteineri põhine lähenemine. Selle protsessi realiseerimiseks kasutatakse järgmisi tarkvarasid:

GIT/GIT CI – kooditarnete tegemine (rakenduse kood, SQL-kood, docker paigaldusfailid, automaattestid). Tarne protsessi automaatne käivitamine. Kasutatakse tellija keskkonda.
Docker – vastavalt GIT-is oleva infole konteinerite loomine ja levitus ( rakendus + andmebaas + rakenduse toimimiseks vajalik infrastruktuur). Docker-iga integreeritud tarkvarad :
- Unit testid – arendaja poolt kirjutatud testid kontrollimaks EHR-i ja selle komponentide toimimist vastavalt nõuetele;
- Apache Maven – Java koodi kompileerimine,
- SonarQube – koodi kvaliteedi kontrolli teostamine,
- Liquibase – andmebaasi loomine ja muutmine,
- Artifactory – Java artifaktide loomine ja konteinerite registreerimine,
- Helm kaartide hoidla.
Kubernetes – konteinerite haldamine, skaleerimine ja koormuse jaotamine.
Katalon – EHR UI ja API testmine.

Joonis 3

Viimati muudetud 18.11.2022

Avatud lähtekood