Retinal CAD

Webová aplikace pro computer-assisted diagnostiku retinálních záznamů s využitím umělé inteligence

Verze 0.1

11. března 2026

1. Introduction

1.1 Purpose

Dokument obsahuje komplexní architektonický přehled systému Retinal CAD - webové aplikace pro počítačem podporovanou diagnostiku záznamů sítnice oka s využitím neuronových sítí. Dokument znázorňuje hlavní architektonické pohledy a reflektuje architektonická rozhodnutí, která byla v souvislosti s vývojem tohoto informačního systému učiněna v několika iteracích, s níchž poslední je zde prezentována.

Použita je šablona Rational Unified Process (RUP), konkrétně pro dokument o softwarové architektuře a obsahuje všechny potřebné pohledy, jak už use-case, logical, process, deployment nebo implementation. Nakonec je uvedena úvaha o výkonu a kvalitě.

1.2 Scope

Systém zahrnuje následující prvky:

• Webové rozhraní pro klinické lékaře a výzkumné pracovníky, které umožňuje nahrávat, prohlížet a analyzovat snímky očního pozadí.

• Počítačem podporovanou diagnostiku prostřednictvím klasifikace struktur sítnice pomocí neuronových sítí založených na umělé inteligenci.

• Správu pacientů a vedení diagnostických záznamů s řízením přístupu pro různé role.

• Administrativní rozhraní pro správu datových sad a datového skladu.

Systém se skládá ze tří nezávisle nasaditelných mikroslužeb. Frontendu SPA založeného na Reactu, backendu Python FastAPI a obrazové API služby Node.js. Všechny služby běží v Docker kontejnerech a jsou nasazeny na infrastruktuře AWS.

1.3 Definitions, Acronyms and Abbreviations

1.4 References

• FastAPI Documentation - https://fastapi.tiangolo.com/

• Strawberry GraphQL Documentation - https://strawberry.rocks/docs

• React Documentation - https://react.dev/

• SQLAlchemy 2.0 Documentation - https://docs.sqlalchemy.org/

• Alembic Documentation - https://alembic.sqlalchemy.org/

• Docker Documentation - https://docs.docker.com/

• AWS Lightsail Documentation - https://docs.aws.amazon.com/lightsail/

• AWS ECR Documentation - https://docs.aws.amazon.com/ecr/

• fastapi-users Documentation - https://fastapi-users.github.io/fastapi-users/

2. Architectural Representation

Dokument představuje architekturu systému Retinal CAD jako soubor pohledů v souladu s přístupem „4+1 View Model“ z Rational Unified Process (RUP):

• Use-case pohled - architektonicky významné případy užití, které definují chování systému.

• Logický pohled - klíčové návrhové balíčky, třídy a jejich uspořádání do vrstev.

• Procesní pohled - souběžné procesy, vlákna a jejich interakce.

• Pohled na nasazení - topologie fyzických uzlů a distribuce služeb v infrastruktuře AWS.

• Pohled na implementaci - organizace zdrojového kódu v rámci polyrepa GitLab.

• Pohled na data - model persistentních dat a schéma databáze.

Všechna architektonická rozhodnutí jsou modelována v notaci UML pomocí diagramů generovaných ze základního návrhového modelu. Systém je implementován jako architektura mikroslužeb se třemi nezávisle nasaditelnými službami komunikujícími přes HTTP.

3. Architectural Goals and Constraints

Klíčové požadavky a systémová omezení mající signifikantní vliv na architekturu:

3.1 Functional Constraints

• Systém musí podporovat tři odlišné uživatelské role – anonymního uživatele, ověřeného uživatele (lékaře/výzkumníka) a správce - z nichž každá má samostatnou sadu povolených operací.

• Klasifikace snímků sítnice pomocí modelu neuronové sítě musí být provedena automaticky po nahrání snímku; výsledky musí být uloženy společně se záznamem o snímku.

• Systém musí udržovat datový sklad kurátorovaných, označených snímků sítnice, který je oddělený od obecného úložiště snímků.

• Záznamy pacientů musí být přístupné bez ověření (anonymizovaný náhled), zatímco operace zápisu vyžadují ověření.

• Veškerý vzdálený přístup podléhá identifikaci uživatele prostřednictvím ověření pomocí tokenu JWT. Jako alternativní ověřovací mechanismus je podporován OAuth2 (např. Google).

3.2 Technical Constraints

• Frontend je implementován jako React SPA obsluhovaná serverem nginx. Musí být možné jej nainstalovat jako PWA pro lokální použití v režimu offline.

• Hlavní backendové API je implementováno v jazyce Python s využitím FastAPI (REST) a Strawberry (GraphQL). Koncové body REST i GraphQL musí být dostupné z jedné služby.

• Služba pro ukládání obrázků je implementována v Node.js s využitím Express. Obrázky jsou uloženy na disku a identifikovány pomocí UUID. Služba je zabezpečena ověřením pomocí API klíče předaného v hlavičkách požadavků.

• PostgreSQL je jedinou relační databází. Schéma databáze je spravováno prostřednictvím ORM SQLAlchemy a verzováno pomocí migrací Alembic.

• Všechny služby jsou kontejnerizovány pomocí Dockeru. Každá služba poskytuje soubor Dockerfile a compose.yml pro lokální vývoj a nasazení.

• Systém je nasazen na AWS: staging používá AWS Lightsail, produkce používá AWS EC2. Dockerové obrazy jsou uloženy v AWS ECR.

• CI/CD pipeline jsou implementovány pomocí GitLab CI/CD. Všechny tři služby jsou umístěny v samostatných GitLab repozitářích pod sdílenou skupinou (strategie polyrepo). Všechny testy jsou prováděny jako součást procesu sestavování Dockeru obrazu, jenž je následně pouze nacachován, díky čemuž jsou nezávislé na infrastruktuře.

3.3 Quality Constraints

• Dostupnost: Produkční prostředí musí být dostupné 24 hodin denně, 7 dní v týdnu. Iterace se řeší pomocí postupného nasazování (testování v testovacím prostředí před nasazením do produkce).

• Zabezpečení: Veškerá komunikace mezi službami při citlivých operacích musí být ověřena (SSL protokol). Pro uživatelské relace se používají tokeny JWT s časovým omezením platnosti.

• Přenositelnost: Služby jsou kontejnerizovány, což je činí přenositelnými napříč prostředími založenými na Linuxu. Jediným požadavkem na infrastrukturu je přítomnost Docker Engine.

• Rozšiřitelnost: Rozdělení na mikroslužby umožňuje jednotlivé služby nezávisle aktualizovat, škálovat nebo nahrazovat.

• Výkon: Inference AI na sítnicových snímcích musí být dokončena v rámci přijatelné latence pro klinické použití (cíl: méně než 10 sekund na snímek)

4. Use-Case View

Tento pohled představuje architektonicky významné případy užití. Popisuje soubor scénářů, které představují klíčové funkce, které mají hlavní architektonické pokrytí a představují co budoucí informační systém bude umět.

Systém definuje tři role uživatelů s následující hierarchií dědičnosti:

• Anonymní uživatel - neověřený návštěvník s přístupem pouze pro čtení k veřejným datům a analytickým nástrojům.

• Ověřený uživatel - zdědí všechny oprávnění anonymního uživatele a získá přístup pro zápis k osobním údajům a nástrojům umělé inteligence.

• Správce - zdědí všechna oprávnění ověřeného uživatele a získá plný přístup k správě systému.

4.1 Architecturally Significant Use Cases

4.2 Use Case Descriptions

4.2.1 UC1 - Registrace Uživatele

4.2.2 UC2 - Přihlášení Uživatele

4.2.3 UC9 - Nahrání snímků retiny

4.2.4 UC8 - Klasifikace snímků retiny

4.2.5 UC6 - Aplikace obrazových filtrů na snímek retiny

5. Logical View

Pohled popisuje nejdůležitější balíčky a jejich uspořádání do vrstev, klíčové třídy a jejich odpovědnosti a hlavní realizace případů použití.

5.1 Architecture Overview - Package and Subsystem Layering

Systém je rozdělen do tří samostatných služeb, z nichž každá má vrstvenou strukturu. Celý systém je postaven na architektuře klient-server s jasným oddělením prezentační, bussiness a datové vrstvy.

5.2 Architecturally Significant Design Packages

5.2.1 Application Layer - React SPA (Frontend Service)

5.2.2 Business Services Layer - FastAPI Backend (Main API Service)

5.2.3 Data Layer - PostgreSQL

5.2.4 Image API Service - Express (Node.js)

5.3 Use-Case Relations

5.3.1 Realisation: Retinal Image Upload + AI Classification

5.3.2 Realisation: Patient Data Visualisation

6. Deployment View

Tato část popisuje fyzickou topologii uzlů, na nichž je systém nasazen. Systém je rozložen na více kontejnerových uzlech v infrastruktuře AWS, přičemž pro lokální vývoj, testování a produkci jsou k dispozici samostatná prostředí.

6.1 Physical Topology

6.2 Deployment Nodes

6.2.1 Developer Workstation

6.2.2 GitLab CI/CD Pipeline

6.2.3 AWS Lightsail (Staging Environment)

6.2.4 AWS EC2 (Production Environment)

6.2.5 AWS ECR (Container Registry)

6.3 Network Configuration

V rámci každého nasazovacího prostředí (stagingového nebo produkčního) komunikují všechny služby prostřednictvím interní sítě Dockeru. Hlavní API komunikuje s Image API prostřednictvím DNS názvu služby Dockeru (např. http://retina-image-provider:3000). Externí přístup je zpřístupněn pouze prostřednictvím kontejneru frontendu nginx (porty 8080/8443). Image API není externě zpřístupněno - přistupuje k němu pouze hlavní API a proxy nginx pro poskytování snímků.

7. Implementation View

Tato část popisuje uspořádání zdrojového kódu ve třech repozitářích GitLabu. Jelikož jsou všechny tři služby spravovány jako samostatné polyrepos pod společnou skupinou GitLab, odpovídá tento model implementace přímo členění služeb v logickém pohledu.

7.1 Repository Structure

7.1.1 Frontend Repository (retina/retina-webapp)

7.1.2 Main API Repository (retina/retina-api)

7.1.3 Image API Repository (retina/retina-image-provider)

7. Layers

8. Data View

Tento pohled popisuje model trvalých dat systému. Všechna klinická data (zdravotní záznamy pacientů, metadata snímků sítnice, diagnózy, uživatelské účty) jsou trvale uložena v databázi PostgreSQL. Převod z návrhového modelu SQLAlchemy do schématu databáze provádí automaticky ORM, přičemž Alembic spravuje postupné změny schématu.

8.1 Data Model Overview

8.2 Database Schema Management

Schéma databáze se generuje automaticky na základě definic modelů v SQLAlchemy. K detekci změn mezi modely ORM a aktuálním schématem databáze se používá nástroj Alembic Autogenerate, který vytváří skripty migrací s verzemi. Historie migrací je uložena v tabulce alembic_version. Migrace se ve všech prostředích aplikují automaticky při spuštění kontejneru.

8.3 Architectural Data Decisions

• Binární data obrázků jsou ukládána mimo relační databázi (na disku, spravována rozhraním Image API), aby se zabránilo přetížení instance PostgreSQL a umožnilo efektivní poskytování souborů prostřednictvím nginx.

• Výsledky klasifikace pomocí AI jsou ukládány ve formátu JSON, aby bylo možné přizpůsobit se měnícím se schématům výstupů modelů, aniž by při aktualizacích modelů bylo nutné provádět migrace databáze.

• Všude se používají primární klíče UUID, aby se zabránilo útokům pomocí sekvenčního číslování ID a umožnilo bezpečné externí zveřejnění identifikátorů entit v URL adresách API.

9. Quality, Size and Performance

Tato část popisuje kvalitativní, objemové a výkonostní požadavky systému, které určují jeho architekturu.

9.1 Sizing Estimates

9.2 Performance Architecture Decision

• Klasifikace pomocí AI se provádí asynchronně po nahrání obrázku, aby nedošlo k zablokování HTTP odpovědi. API okamžitě vrátí odpověď 202 Accepted - klient pak buď pravidelně dotazuje na výsledek klasifikace, nebo obdrží push notifikaci přes WebSocket.

• Image API ukládá soubory na lokální disk (svazek Dockeru), čímž se vyhýbá přenosům binárních dat do databáze a umožňuje serveru nginx poskytovat obrázky přímo přes X-Accel-Redirect pro maximální propustnost.

• Asynchronní režim SQLAlchemy (ovladač asyncpg) se používá k maximalizaci souběžnosti ve smyčce událostí FastAPI bez blokování pracovních vláken.

• Je nakonfigurován fond připojení PostgreSQL (výchozí: 10–20 připojení na Uvicorn workera), který zpracovává souběžné požadavky, aniž by vyčerpal databázová připojení.

• Statické frontendové soubory (balíčky JS, CSS) jsou poskytovány přímo nginxem s hlavičkami cache-control, aby se minimalizovaly opakované přenosy v síti.

9.3 Security

Authentication - Ověřování založené na JWT s nastavitelnou dobou platnosti tokenů (výchozí přístupový token: 1 hodina; obnovovací token: 30 dní). Jako alternativní způsob přihlášení je podporován protokol OAuth2 (Google).

Authorisation - Řízení přístupu na základě rolí (RBAC) je vynucováno na úrovni závislostí FastAPI. Každý koncový bod deklaruje požadovanou roli, systém pomocí dependency injection odmítá požadavky od uživatelů s nedostatečnými oprávněními s chybovým kódem HTTP 403.

Image API security - Rozhraní API pro obrázky není veřejně přístupné. Ověřování pomocí klíče API zabraňuje neoprávněnému zápisu. UUID v názvech obrázků brání útokům typu enumerace.

Password storage - Hesla se před uložením zašifrují pomocí algoritmu bcrypt, hesla v otevřeném textu se nikdy neukládají.

HTTPS - V produkčním prostředí je terminace TLS zpracovávána na úrovni reverzního proxy serveru nginx. Veškerá externí komunikace je šifrována. Certifikáty jsou uděleny certifikační autoritou Lets Encrypt.

9.4 Reliability and Availability

Target availability - 99,5% provozuschopnost na produkci (přibližně 44 hodin výpadku ročně).

Deployment strategy - Blue/green nasazení nebo postupné nasazení prostřednictvím restartu docker kontejneru minimalizují prostoje během aktualizací.

Data durability - Data a obrazové soubory PostgreSQL jsou v produkčním prostředí ukládány na svazcích EBS s automatickými snapshoty.

Health checks - Každá služba poskytuje koncový bod /health. Docker Compose a nástroj pro koordinaci nasazení je využívají k monitorování stavu kontejnerů a k automatickému restartu v případě selhání.

9.5 Maintainability

Polyrepo - Každá služba je umístěna ve vlastním repozitáři s vlastním CI/CD procesem, což umožňuje nezávislé cykly vydávání a omezuje dopad změn.

Database migrations - Migrační skripty Alembic jsou spravovány v rámci systému správy verzí a při nasazení se aplikují automaticky, čímž je zajištěna konzistence schématu napříč prostředími.

Type safety - FastAPI využívá pro všechna schémata požadavků a odpovědí modely Pydantic. Strawberry používá pro schéma GraphQL typové anotace v jazyce Python. Komponenty Reactu využívají TypeScript.

9.6 Portability

Containerisation - Všechny služby jsou kontejnerizovány pomocí Dockeru. Jediným požadavkem na infrastrukturu je Docker Engine. Služby lze spouštět na jakémkoli hostitelském počítači s operačním systémem Linux (místní notebook, AWS Lightsail, AWS EC2, lokální server).

Environment Configuration - Všechna nastavení specifická pro dané prostředí (URL databáze, klíče API, tajné kódy JWT, přihlašovací údaje AWS) se zadávají prostřednictvím proměnných prostředí v souladu s metodikou 12-factor app.

9.7 Testability

Test-in-Docker - Všechny testy (jednotkové, integrační) se provádějí jako součást sestavení v Dockeru. Kromě Docker Engine není zapotřebí žádná další testovací infrastruktura. Tím je zajištěno, že testy proběhnou ve stejném prostředí jako produkční provoz.

Test coverage - Backend FastAPI využívá pytest spolu s pytest-asyncio pro podporu asynchronního testování. Frontend React využívá Vitest nebo Jest, popřípadě Playwright. Image API využívá Jest.

Staging Environment - Vyhrazené testovací prostředí na AWS Lightsail kopíruje produkční konfiguraci a slouží ke komplexnímu testování před nasazením do produkčního prostředí.

9.8 Usability

PWA Support - React SPA lze nainstalovat jako progresivní webovou aplikaci na stolní počítače i mobilní zařízení, čímž poskytuje zážitek podobný nativní aplikaci a ukládání do mezipaměti v offline režimu.

Accessibility - Komponenty uživatelského rozhraní splňují pokyny WCAG 2.1 AA díky Radix UI komponentám, kde je to možné, a zajišťují tak přístupnost pro uživatele se zrakovým postižením.

Responsive design - Uživatelské rozhraní se přizpůsobuje různým velikostem obrazovky, aby bylo možné jej používat jak na klinických pracovních stanicích, tak na tabletech.