R-TF-012-029 Software Architecture Description

Purpose

This document describes the software architecture for the device, including the system structure, software items, interfaces, data flows, and design rationale. It provides the architectural framework that guides implementation of the requirements defined in the Software Requirements Specification (SRS) and establishes the foundation for detailed design activities.

This architecture description is developed in accordance with IEC 62304:2006+AMD1:2015 and serves as the primary reference for understanding how the software system is organized and how its components interact.

Scope

This architecture description covers:

• High-level software architecture and system decomposition into software items
• Responsibilities of each software item and its constituent software units
• Interfaces between software items and with external systems
• Integration of SOUP (Software of Unknown Provenance) components
• Data flow and control flow through the system
• Architectural decisions and their justifications

This document does not cover detailed design specifications for individual software units, which are addressed in the Software Detailed Design documentation. Complete API specifications are maintained in a separate API reference document.

Terminology

The following terms are used throughout this document. Terms marked with (IEC 62304) are defined in accordance with that standard:

IEC 62304 terms:

• Software item (IEC 62304): A separately identifiable part of the software system, composed of one or more software units.
• Software unit (IEC 62304): The smallest testable element of a software item.
• SOUP (IEC 62304): Software of Unknown Provenance—software that was not developed for the purpose of being incorporated into the medical device.

Domain-specific terms:

• Expert: A specialized software item that executes a specific AI model for clinical analysis (e.g., classification, segmentation, or detection).
• Integrator: A third-party organization or developer that incorporates the device's API into their own application to provide clinical functionality to end users.
• Canonical: A standardized, internal data format used for communication between software items, independent of external interface formats.
• Workflow: A defined sequence of processing steps that the device executes to fulfill a clinical request (e.g., the diagnosis support workflow or severity assessment workflow).

Architectural pattern terms:

• ACL (Anti-Corruption Layer): A pattern that isolates one subsystem from another by translating between their data models, preventing external schemas from leaking into domain logic.
• DTO (Data Transfer Object): A simple object that carries data between processes or layers without containing business logic.
• Port: An interface that defines how a component interacts with external systems, enabling substitution of implementations.
• Adapter: A concrete implementation of a port that connects to a specific external system or technology.

Architectural overview

This section presents the system's purpose, clinical workflows, main functions, and external interfaces at a conceptual level. Subsequent sections provide detailed decomposition of each software item.

System purpose and clinical workflows

The device provides image analysis workflows for dermatological conditions as specified in the Intended Use. Integrators access these workflows through a RESTful API that supports two primary clinical functions:

• Diagnosis support: Accepts up to 5 images of a skin condition and returns a probability distribution across ICD diagnostic categories.
• Severity assessment: Accepts a single image plus optional patient-reported information (e.g., itch intensity, sleep disturbance) and returns quantified clinical sign assessments.

Both workflows follow a common processing pipeline:

1. Request submission: The integrator selects a workflow type and submits the required data (images and optional parameters).
2. Validation: The device validates submitted images for quality and domain relevance before proceeding with analysis.
3. Expert analysis: The device routes the request to the appropriate AI model experts, which process the images and generate clinical findings.
4. Report generation: Results from the experts are assembled into a structured clinical report and returned to the integrator.

Diagnosis support workflow

The diagnosis support workflow accepts up to 5 images of a skin condition. After validating images for quality and domain relevance, the device invokes the Condition Classification expert, which performs multi-image analysis with aggregation. The response includes:

• Aggregated ICD probability distribution across the image set (SRS-Q3Q)
• Per-image ICD diagnosis with explainability heat maps (SRS-0AB)
• Model sensitivity and specificity metrics (SRS-1XR)
• Entropy score indicating prediction uncertainty (SRS-58W)
• Clinical risk indicators:
  • High priority referral indicator (SRS-71I)
  • Malignancy indicator (SRS-8HY)
  • Pigmented lesion indicator (SRS-D08)
  • Condition presence indicator (SRS-JLM)
  • Urgent referral indicator (SRS-KAS)

Severity assessment workflow

The severity assessment workflow accepts a single image along with optional patient-reported information. After image validation, the device invokes the requested expert services—which may include sign classifiers, segmenters, and detectors—to process the image in parallel. The combined results provide a quantitative assessment of clinical signs.

The architecture supports four categories of expert outputs:

• Classification: Binary presence/absence detection and continuous severity scoring for clinical signs (e.g., erythema intensity, wound characteristics, tissue depth)
• Segmentation: Pixel-level masks quantifying the spatial extent of features (e.g., lesion area, erythema coverage), with both probabilistic and binary outputs
• Detection: Object localization with bounding boxes for discrete structures (e.g., papules, nodules, pustules), including counts and confidence scores
• Staging: Multi-class classification for standardized severity scales (e.g., wound staging, Hurley staging for hidradenitis suppurativa, IGA grading for acne)

The specific clinical signs and expert models supported are documented in the Software Requirements Specification.

Main functions

The software architecture supports the following primary functions:

Function	Description
Image quality assessment	Assesses image quality using CNN-based scoring (1-10 scale) combined with technical requirements validation (minimum size, aspect ratio, color detection) to determine acceptability for clinical analysis
Image domain and modality classification	Classifies images as dermatological or non-dermatological, and for dermatological images, identifies the imaging modality (clinical photograph vs. dermoscopy)
Diagnosis support	Generates a probability distribution across ICD categories by analyzing one or more images, with per-condition confidence scores and explainability outputs
Severity assessment	Quantifies clinical signs through classification (intensity), segmentation (spatial extent), and detection (lesion counts)
Report generation	Transforms raw expert outputs into structured clinical reports with standardized medical terminology (ICD-11, SNOMED CT)
API exposure	Provides secure, versioned access to device functionality through a RESTful interface with authentication and audit logging

External interfaces

The device exposes its functionality exclusively through a RESTful API, which serves as the sole interface for integrators. All communication uses JSON over HTTPS with JWT-based authentication.

API structure

The API Gateway organizes endpoints into four categories:

Category	Purpose	Authentication
Authentication	User login and token management	None
Clinical	Diagnosis support and severity assessment	Required
Device	Device information and health checks	Required
Internal	System monitoring (not in public API schema)	Required

Authentication model

Integrators authenticate using the OAuth2 Password Grant flow:

1. The integrator submits credentials (username and password) to POST /auth/login
2. Upon successful authentication, the API returns a signed JWT with a limited validity period
3. The integrator includes this JWT as a Bearer token in subsequent requests
4. When the token expires, the integrator must re-authenticate

This model ensures that access is credential-based, time-limited, and regularly re-validated.

POST /auth/login

Authenticates a user with username and password and returns a JWT access token for accessing protected endpoints.

Request headers:

Content-Type: application/json

Request body:

{
  "username": "integrator@example.com",
  "password": "securePassword123"
}

Response body (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Error responses:

• 401 Unauthorized: Invalid username or password, or password has expired
• 403 Forbidden: Account is locked due to excessive failed login attempts
• 429 Too Many Requests: Login temporarily delayed after failed attempts (includes Retry-After header)

Clinical endpoints

The clinical endpoints correspond directly to the device's clinical workflows.

POST /clinical/diagnosis-support

Accepts 1–5 base64-encoded images of the suspected lesion from different perspectives and returns a report with possible diagnoses, including:

• A probability distribution across ICD diagnostic categories (both aggregated across all images and per-image)
• Explainability outputs (saliency heat maps) for top predictions
• Clinical risk indicators (malignancy, urgent referral, etc.)

Request headers:

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Request body:

{
  "images": [
    {
      "identifier": "550e8400-e29b-41d4-a716-446655440000",
      "data": "/9j/4AAQSkZJRgABAQEASABIAAD...",
      "color_model": "RGB",
      "file_format": "JPEG"
    }
  ],
  "extra_parameters": {
    "common": {},
    "expert_specific": {}
  }
}

Field	Type	Required	Description
images	array	Yes	1–5 base64-encoded images representing different views of the target area
images[].identifier	UUID	No	Unique identifier for the image (auto-generated if omitted)
images[].data	string	Yes	Base64-encoded image data
images[].color_model	string	No	Color model of the image (default: RGB)
images[].file_format	string	No	Image file format (default: JPEG)
extra_parameters	object	No	Additional configuration parameters for the analysis experts

Response body (200 OK):

{
  "study_aggregate": {
    "findings": {
      "hypotheses": [
        {
          "identifier": "psoriasis",
          "concepts": [
            {
              "name": "Psoriasis",
              "code": "9014002",
              "terminology_system": "SNOMED CT"
            }
          ],
          "probability": 78.5,
          "explanation": {
            "attention_map": {
              "data": "/9j/4AAQSkZJRgABAQEASABI...",
              "color_model": "RGB",
              "file_format": "PNG"
            }
          }
        },
        {
          "identifier": "eczema",
          "concepts": [
            {
              "name": "Eczema",
              "code": "43116000",
              "terminology_system": "SNOMED CT"
            }
          ],
          "probability": 15.2,
          "explanation": null
        }
      ],
      "risk_metrics": {
        "any_condition_probability": 95.8,
        "malignant_condition_probability": 2.1,
        "pigmented_condition_probability": 5.4,
        "urgent_referral_probability": 3.2,
        "high_priority_referral_probability": 12.7
      },
      "entropy": 28.4
    }
  },
  "image_analyses": [
    {
      "source_image": {
        "identifier": "550e8400-e29b-41d4-a716-446655440000"
      },
      "findings": {
        "hypotheses": [...],
        "risk_metrics": {...},
        "entropy": 25.1
      }
    }
  ]
}

POST /clinical/severity-assessment

Accepts a single base64-encoded image and a list of visual sign expert identifiers, and returns:

• Sign assessments including intensity scores, segmentation masks, and detection counts
• Annotated images showing detected regions

Request headers:

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Request body:

{
  "image": {
    "identifier": "550e8400-e29b-41d4-a716-446655440001",
    "data": "/9j/4AAQSkZJRgABAQEASABIAAD...",
    "color_model": "RGB",
    "file_format": "JPEG"
  },
  "experts": ["erythema", "scaling", "induration"],
  "extra_parameters": {
    "common": {},
    "expert_specific": {}
  }
}

Field	Type	Required	Description
image	object	Yes	Base64-encoded image representing the target area to be analyzed
experts	array	Yes	List of visual sign expert identifiers to be consulted (e.g., erythema, scaling, induration, excoriation)
extra_parameters	object	No	Additional configuration parameters for the analysis experts

Response body (200 OK):

{
  "image_analysis": {
    "source_image": {
      "identifier": "550e8400-e29b-41d4-a716-446655440001"
    },
    "findings": [
      {
        "sign_identifier": "erythema",
        "overall_severity_summary": "Moderate erythema",
        "presence": {
          "is_present": true,
          "confidence": 98.2
        },
        "intensity": {
          "grade": 2.5,
          "grading_scale": "Legit.Health",
          "confidence": 87.3
        },
        "extent": {
          "regions": [
            {
              "mask": {
                "data": "/9j/4AAQSkZJRgABAQEASABI...",
                "color_model": "RGB",
                "file_format": "PNG"
              },
              "threshold": 0.5,
              "confidence_map": {
                "data": "/9j/4AAQSkZJRgABAQEASABI...",
                "color_model": "RGB",
                "file_format": "PNG"
              },
              "percentage": 35.2,
              "label": "affected_area"
            }
          ],
          "annotated_image": {
            "data": "/9j/4AAQSkZJRgABAQEASABI...",
            "color_model": "RGB",
            "file_format": "PNG"
          }
        }
      },
      {
        "sign_identifier": "scaling",
        "overall_severity_summary": "Mild scaling",
        "intensity": {
          "grade": 1.2,
          "grading_scale": "Legit.Health",
          "confidence": 91.5
        }
      }
    ]
  }
}

GET /clinical/severity-experts

Returns the list of valid visual sign expert identifiers that can be used in the severity-assessment endpoint.

Request headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response body (200 OK):

{
  "experts": [
    "erythema",
    "scaling",
    "induration",
    "excoriation",
    "lichenification",
    "dryness",
    "edema",
    "vesiculation"
  ]
}

Both clinical endpoints return structured JSON responses with standardized medical terminology codes (ICD-11, SNOMED CT) where applicable.

Device endpoints

GET /device/about

Returns device labeling information including manufacturer details, regulatory clearances, UDI, and applicable standards.

Request headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response body (200 OK):

{
  "device_name": "Device Name",
  "description": "AI-powered clinical decision support system for dermatological conditions...",
  "version": "1.1.0.0",
  "release_date": "2024-01-15",
  "manufacturer": {
    "name": "Manufacturer Name",
    "description": "Digital health solutions developer",
    "country_code": "ES",
    "website": "https://example.com"
  },
  "udi": "(01)08437025130011(10)1.1.0.0(21)PROD-001",
  "alternate_identifiers": [
    {
      "system": "GMDN",
      "code": "47905",
      "issuing_authority": "GMDN Agency",
      "description": "Software as a medical device"
    }
  ],
  "standards": [
    {
      "standard_name": "ISO 13485",
      "standard_version": "2016"
    },
    {
      "standard_name": "IEC 62304",
      "standard_version": "2006+AMD1:2015"
    }
  ],
  "regulatory_clearances": [
    {
      "regulation": "EU_MDR_2017_745",
      "risk_class": "IIa",
      "notified_body": "BSI",
      "authorization_id": "CE123456",
      "authorization_date": "2024-01-10"
    }
  ],
  "claims": [
    {
      "description": "User may request IFU in paper format",
      "reference": "EU MDR Article 7(2)"
    }
  ],
  "contact_email": "support@example.com",
  "instructions_url": "https://ifu.example.com/eu-mdr"
}

GET /device/health

Returns the operational status of the device and its downstream services.

Request headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response body (200 OK):

{
  "status": "healthy",
  "services": {
    "control_plane": {
      "status": "healthy",
      "latency_ms": 45
    },
    "expert_orchestrator": {
      "status": "healthy",
      "latency_ms": 120
    },
    "database": {
      "status": "healthy",
      "latency_ms": 12
    }
  }
}

Error handling

All endpoints use standard HTTP status codes:

Status	Meaning
200 OK	Request succeeded
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	User account is locked or inactive
429 Too Many Requests	Rate limit exceeded or login delayed
503 Service Unavailable	Downstream service (e.g., Control Plane) unavailable

Error response format:

All error responses follow a consistent JSON structure:

{
  "detail": "Invalid username or password"
}

For rate-limited requests, the response includes a Retry-After header indicating when the client may retry:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "detail": "Too many failed login attempts. Please wait 30 seconds before retrying."
}

Global system views

This section presents the system from multiple architectural perspectives—deployment topology, component connections, data flow, and security boundaries—before the detailed decomposition of individual software items in the following section.

Deployment architecture

The device is deployed on AWS infrastructure. The following diagram illustrates the deployment topology and key AWS services used:

Component connections

The following diagram shows the communication paths between software items. External integrators access the device through the API Gateway over HTTPS. Internal communication between software items uses HTTP within the private network. The experts—specialized software items that execute AI models—are accessed through the Expert Orchestrator.

Data flow

Data flows through the system as JSON payloads. The following diagram shows the data paths and the types of data exchanged between components:

The following sequence diagram illustrates the general request processing flow, showing how data transforms as it passes through each layer:

Updatability and versioning

The architecture supports controlled updates through a defined versioning scheme and deployment process:

Software versioning follows a four-digit scheme (W.X.Y.Z) as defined in GP-012:

• W (major): Reserved for fundamental architectural changes
• X (feature): Incremented for significant feature additions or backward-incompatible changes
• Y (minor): Incremented for minor improvements
• Z (patch): Incremented for bug fixes

API versioning follows an independent scheme (vA.B) decoupled from the software version. API version changes reflect contract modifications; backward compatibility requirements are documented in the API Gateway to ensure integrators can plan transitions.

Deployment process: New software versions are deployed to production only after completing all required verification and validation activities. The containerized architecture allows individual software items to be updated independently, enabling targeted patches without full system redeployment.

Security architecture

This section describes the security mechanisms implemented at the architectural level to protect data confidentiality, integrity, and system access.

API access control

Integrators access the device API using secure, credential-based authentication. Each integrator is assigned unique username and password pairs, which they use to log in via the API's authentication endpoint. Upon successful login, the API issues a signed JWT (JSON Web Token) that grants temporary access to clinical endpoints. This token is valid for a limited period; once it expires, the integrator must re-authenticate to obtain a new JWT and continue accessing the API. This mechanism ensures that only authorized users can interact with the device API, and that access is regularly validated.

User database access control

The DynamoDB table containing user records is protected through AWS IAM and the principle of least privilege:

• No long-lived credentials: The API service assumes a dedicated IAM role rather than using static credentials.
• Temporary credentials: AWS issues short-lived, automatically rotated credentials each time the role is assumed.
• Minimum permissions: The IAM role grants only the permissions required for user management operations.
• No direct external access: Only the API Gateway can access the user database; integrators and external systems have no direct connection to DynamoDB.
• Request signing: All requests to DynamoDB use AWS Signature Version 4, ensuring authenticity and integrity.

Audit log protection

Audit records are stored in a dedicated DynamoDB table with controls designed to ensure immutability and tamper resistance:

• Write-only access: The API service assumes a specialized IAM role that grants write permissions only—no read, modify, or delete operations are permitted.
• Append-only design: The API cannot modify or delete existing audit entries, preserving a reliable chronological record of system activity.
• No external access: Audit writes can only occur through the API service; no external system or integrator has direct access to the audit table.
• Request signing: All writes use AWS Signature Version 4, ensuring the authenticity and integrity of every audit record.

Software item decomposition

This section describes each software item in detail, including its responsibilities, constituent software units, SOUP dependencies, and interfaces with other software items. Each software item is presented using a consistent structure:

1. Overview: Purpose and primary responsibilities
2. Software units: Internal components that implement the software item's functionality
3. SOUPs: Third-party libraries on which the software item depends
4. Interfaces: Connections to other software items and external systems

System overview

The software system comprises five categories of software items:

• API Gateway, which exposes the device's functionalities to integrators through a RESTful API and handles authentication, authorization, and audit logging.
• Control Plane, which orchestrates the device's internal operations, manages requests, and coordinates interactions between the Expert Orchestrator and Report Builder.
• Expert Orchestrator, which coordinates the execution of expert services, routing analysis requests to the appropriate experts and aggregating their results.
• Report Builder, which transforms expert analysis results into canonical clinical reports with standardized medical terminology.
• Experts, which are individual software items that implement specific AI models for diagnosis support, severity assessment, and other clinical and non-clinical functionalities.

The following diagram illustrates the high-level decomposition of the software system and the relationships between its components:

API Gateway (User Interface)

The API Gateway software item provides an HTTP-based entry point that allows integrator applications to access the device's clinical services. It exposes RESTful endpoints for authentication, diagnosis support, severity assessment, and device information retrieval. All requests and responses use JSON format, and protected endpoints require JWT-based authentication. The API Gateway delegates clinical processing to the Control Plane and records all API calls for audit purposes.

The API Gateway is composed of the following software units:

1. HTTP Routes: FastAPI router modules (auth, clinical, device, internal) that define endpoint handlers for authentication (/auth/login), clinical analysis (/clinical/diagnosis-support, /clinical/severity-assessment), device information (/device/about, /device/health), and internal status monitoring (/internal/status).

2. Authentication Dependencies: Middleware components that extract and validate JWT bearer tokens from incoming requests and verify that the authenticated user is active in the system.

3. Use Cases: Application layer components (LoginUseCase, DiagnosisUseCase, SeverityAssessmentUseCase, GetDeviceLegalInfoUseCase, GetDeviceHealthUseCase, GetDeviceStatusUseCase, RecordCallUseCase) that orchestrate business operations by coordinating domain services and outbound adapters.

4. Domain Services: The AccountSecurityService implements account lockout policies, managing failed login attempts and determining when to lock accounts based on configurable thresholds.

5. Outbound Adapters: Implementations of port interfaces including:

   • HTTPControlPlaneClient: HTTP client adapter that communicates with the Control Plane for clinical analysis requests and device information.
   • DynamoDBUserRepository, DynamoDBLockoutRepository, DynamoDBCallRecordRepository: Persistence adapters for user accounts, lockout records, and API call audit logs.
   • Argon2AuthenticationService: Password hashing and verification using the Argon2 algorithm.
   • JwtTokenService: JWT generation and validation for access tokens.

6. Call Recording Middleware: A Starlette middleware (CallRecorderMiddleware) that intercepts all API requests and responses, capturing metadata (timing, authentication context, HTTP details, client information) and asynchronously persisting audit records.

7. Dependency Injection Container: A Dependency Injector container (Container) that wires together all services, repositories, use cases, and configuration, ensuring proper initialization and dependency management.

SOUPs

The API Gateway leverages the following SOUP items:

• FastAPI: Web framework for building the HTTP API with automatic validation and OpenAPI documentation.
• Uvicorn: ASGI server for running the FastAPI application.
• Authlib: JWT encoding and decoding for access token generation and validation.
• Argon2-cffi: Secure password hashing using the Argon2 algorithm.
• HTTPX: Asynchronous HTTP client for communication with the Control Plane.
• aioboto3: Asynchronous AWS SDK client for DynamoDB operations.
• Pydantic: Data validation and settings management for request/response models and configuration.
• Dependency Injector: Dependency injection framework for wiring application components.

Interfaces with other software items

The API Gateway interacts with the following software items and external systems:

• Control Plane: Receives delegated requests for diagnosis support, severity assessment, and device information via HTTP calls. The Control Plane orchestrates downstream processing through expert modules and report generation.
• Users Database (DynamoDB): Stores user account information including credentials and organization membership.
• Lockouts Database (DynamoDB): Maintains account lockout state for security enforcement.
• API Calls Database (DynamoDB): Persists audit records of all API calls for traceability and compliance.
• Integrator Application: External client applications that consume the API endpoints using JSON over HTTP with JWT bearer authentication.

The following figure depicts the API Gateway architecture and its relations with other software items.

Control Plane

The Control Plane is the orchestration layer of the device backend. It receives requests from the API interface and coordinates the internal workflow needed to produce a clinical report. Its primary responsibility is to route user input through the appropriate expert services and report-building pipeline, returning a fully structured canonical report to the caller.

The Control Plane software item comprises the following software units:

1. REST HTTP Controller: Exposes HTTP endpoints for clinical workflows, device information, and health checks. The controller receives incoming requests from the API interface, validates input using Pydantic data models from the shared interface models library, and delegates processing to the appropriate use case.

2. Diagnosis Workflow Use Case: Orchestrates the complete diagnosis workflow. It receives user diagnosis input, forwards it to the Expert Orchestrator to obtain expert analysis results, and then sends those results to the Report Builder to generate the final canonical diagnosis report.

3. Severity Workflow Use Case: Orchestrates the complete severity assessment workflow. It follows the same pattern as the diagnosis workflow, coordinating between the Expert Orchestrator and Report Builder to produce a canonical severity report.

4. Health Check Use Case: Aggregates health status from downstream services (Expert Orchestrator and Report Builder) to provide a comprehensive backend health assessment. It invokes health endpoints on each downstream service and returns an aggregated status indicating whether all services are operational.

5. Get Device Label Use Case: Retrieves device labeling information (regulatory details, manufacturer information, UDI) from an S3-stored JSON file. This information is used by the API interface to expose device metadata to integrators.

6. Expert Orchestrator Gateway: An outgoing adapter that communicates with the Expert Orchestrator microservice via HTTP. This gateway abstracts the details of the HTTP transport and provides a domain-oriented interface for invoking expert analysis on user input.

7. Report Builder Gateway: An outgoing adapter that communicates with the Report Builder microservice via HTTP. This gateway abstracts the HTTP communication required to transform expert results into canonical report structures.

8. Health Checker Gateway: An outgoing adapter that performs HTTP health checks against downstream services. It handles both successful responses and 503 responses (which may contain detailed health information).

9. S3 Device Label Repository: An outgoing adapter that retrieves the device label JSON file from AWS S3 storage. It uses the boto3 SDK to access S3 and parses the retrieved JSON into the MedicalDeviceInfo data model.

10. HTTP Client: A shared infrastructure component that manages persistent HTTP connections with retry logic and exponential backoff. It is used by the outgoing gateways to perform HTTP requests to downstream services.

11. Dependency Injection Container: Manages the lifecycle of all application components using the dependency-injector library. It wires configuration, gateways, use cases, and infrastructure components, ensuring proper initialization and shutdown of resources.

12. Settings Configuration: Loads application settings from environment variables using pydantic-settings. This includes service metadata, server configuration, downstream service URLs, HTTP client parameters, and S3 configuration for device label storage.

SOUPs

The Control Plane directly uses the following SOUP items:

• FastAPI: A modern Python web framework used to implement the REST API endpoints.
• Uvicorn: An ASGI server used to run the FastAPI application.
• Pydantic and pydantic-settings: Used for data validation, serialization, and configuration management.
• dependency-injector: A dependency injection framework used to manage component wiring and lifecycle.
• httpx: An asynchronous HTTP client library used for communication with downstream microservices.
• boto3: AWS SDK for Python, used to retrieve the device label JSON file from S3 storage.
• legithp-interface-models: A shared internal library that provides canonical data models for user input, expert results, and reports.
• legithp-essentials: A shared internal library providing utilities including S3 client creation and JSON file reading functions.

Interfaces with other software items

The Control Plane interfaces with the following software items:

• API Gateway: The Control Plane receives HTTP requests from the API Gateway at the /clinical-workflows/diagnosis, /clinical-workflows/severity, /legal-info, /health, and /backend-health endpoints.
• Expert Orchestrator: The Control Plane invokes the Expert Orchestrator via HTTP to process user input and obtain clinical analysis results from expert AI/ML models.
• Report Builder: The Control Plane sends expert results to the Report Builder via HTTP to generate structured canonical reports.
• AWS S3: The Control Plane retrieves the device label information from an S3 bucket containing the device's regulatory and manufacturer details.

The following figure depicts the Control Plane architecture and relations with other software items.

Report Builder

The Report Builder software item is responsible for transforming expert analysis results into canonical clinical reports. It receives structured outputs from AI/ML experts (via the Control Plane) and constructs standardized diagnosis and severity reports that can be consumed by downstream components such as the Report exporter or the API interface. The module applies domain rules, aggregates per-image findings into study-level assessments, calculates risk metrics, and optionally enriches reports with standardized medical terminology codes (ICD-11, SNOMED-CT).

The Report Builder is composed of the following software units:

1. Generate Diagnosis Report Use Case: Orchestrates the generation of diagnosis reports. It invokes the assembler to translate expert results into domain aggregates, optionally enriches hypotheses with medical terminology codes via the Terminology Enrichment Service, and delegates to the presenter to produce the canonical DTO output.

2. Generate Severity Report Use Case: Orchestrates the generation of severity reports from sign-based expert results. It invokes the assembler and presenter to produce the canonical severity report DTO.

3. Diagnosis Report Assembler (DiagnosisReportAssembler): An inbound ACL component that translates DiagnosisExpertResults into domain aggregates. It creates differential diagnoses with ranked hypotheses, extracts risk assessment metrics (with indicator name mapping), and constructs per-image analyses including technical assessments.

4. Severity Report Assembler (SeverityReportAssembler): An inbound ACL component that translates SeverityExpertResults into domain aggregates. It coordinates an extractor pipeline that processes multiple data sources (classifiers, segmenters, detectors) and builds sign assessments with presence, intensity, extent, count, staging, and characteristics dimensions.

5. Dimension Extractors: A pipeline of protocol-based extractors (ClassifierExtractor, PresenceExtractor, SegmentationExtractor, DetectionExtractor, InflammatoryPatternExtractor) that extract specific dimensions from expert results. A DimensionMerger resolves conflicts using priority-based selection when multiple extractors provide the same dimension.

6. Domain Aggregates (core/domain/aggregates/): DiagnosisReport and SeverityReport are the aggregate roots that encapsulate report business logic, enforce invariants, and provide methods for querying risk levels and assessable image counts.

7. Domain Entities (core/domain/entities/): Include DifferentialDiagnosis, Hypothesis, RiskAssessment, ImageAnalysis, SignAssessment, SignPresence, SignIntensity, SignExtent, LesionCount, SignStaging, SignCharacteristic, and TechnicalAssessment. These represent the clinical concepts and findings within a report.

8. Domain Factories (core/domain/factories/): RiskAssessmentFactory validates required metrics and constructs risk assessments from metric dictionaries, supporting both decimal (0-1) and percentage (0-100) input formats.

9. Diagnosis Report Presenter (DiagnosisReportPresenter): An outbound ACL component that translates the DiagnosisReport domain aggregate into the CanonicalDiagnosisReport DTO. It builds study-level aggregates with differential diagnoses, converts risk scores to percentages, and includes saliency maps as explanations for top hypotheses.

10. Severity Report Presenter (SeverityReportPresenter): An outbound ACL component that translates the SeverityReport domain aggregate into the CanonicalSeverityReport DTO. It converts sign assessments to the canonical format including presence, intensity grades, segmentation regions with masks, detection counts with bounding boxes, staging information, and characteristics.

11. Terminology Enrichment Service: An application service that enriches diagnosis hypotheses with medical terminology codes (ICD-11, SNOMED-CT) by looking up condition identifiers in the terminology repository.

12. Terminology Repository Port and Adapter: Defines an abstract port for medical terminology lookups and provides a JSON file–based adapter (JsonTerminologyRepository) that loads ICD-11 and SNOMED-CT mappings from terminology.json with case-insensitive lookups.

13. REST Inbound Adapter (infrastructure/adapters/inbound/rest/): Exposes HTTP endpoints (/reports/diagnosis, /reports/severity, /ready) via FastAPI routers. The adapter receives expert results as JSON payloads, invokes the appropriate use case, and returns canonical report DTOs.

14. Dependency Injection Container (di.py): Configures and wires application dependencies using the dependency-injector library, including conditional creation of the terminology enrichment service based on configuration.

SOUPs

The Report Builder directly uses the following SOUP items:

• FastAPI: Web framework used to expose the REST API endpoints.
• Uvicorn: ASGI server used to run the FastAPI application.
• Pydantic / pydantic-settings: Used for data validation, settings management, and request/response serialization.
• dependency-injector: Provides the dependency injection container for wiring application components.
• httpx: HTTP client library (declared as a dependency, available for potential outbound HTTP calls).

Additionally, the Report Builder depends on internal monorepo libraries:

• legithp-interface-models: Provides shared data models for expert results and canonical reports.
• legithp-essentials: Provides utility functions such as JSON file reading.

Interfaces with other software items

The Report Builder interfaces with other software items as follows:

• Control Plane: The Control Plane invokes the Report Builder over HTTP, sending DiagnosisExpertResults or SeverityExpertResults payloads and receiving canonical reports. The Control Plane uses an HttpReportBuilderGateway adapter to communicate with the Report Builder's REST endpoints.
• Expert Orchestrator / Experts: The Report Builder does not communicate directly with expert components; instead, it receives aggregated expert results from the Control Plane.
• API Gateway: The canonical reports produced by the Report Builder are returned to the Control Plane, which forwards them to the API Gateway for delivery to end users.
• Terminology Data: The Report Builder reads medical terminology mappings from a JSON file (terminology.json) stored locally in the data/ directory.

The following diagram depicts the Report Builder architecture and its relationships with other software items.

Expert Orchestrator

The Expert Orchestrator is the coordination layer responsible for routing analysis requests to the appropriate expert services and aggregating their results. It receives workflow requests from the Control Plane and manages the parallel or sequential execution of multiple expert services to produce comprehensive analysis results.

The Expert Orchestrator software item comprises the following software units:

1. REST HTTP Controller: Exposes HTTP endpoints for diagnosis and severity workflows (/workflow/diagnosis, /workflow/severity) as well as health and readiness endpoints (/health, /ready). The controller receives incoming requests from the Control Plane, validates input, and delegates processing to the appropriate use case.

2. Run Diagnosis Workflow Use Case: Orchestrates the diagnosis workflow by creating a multi-step workflow that first processes each image through IMAGE_QUALITY and IMAGE_DOMAIN_MODALITY experts in parallel, then processes all images together through the CONDITION_CLASSIFIER expert. Results are aggregated and mapped to the DiagnosisExpertResults output model.

3. Run Severity Workflow Use Case: Orchestrates the severity assessment workflow by executing the selected sign experts (classifiers, segmenters, detectors) on the input image. The workflow supports parallel execution of all experts and aggregates results into the SeverityExpertResults output model.

4. Check Experts Readiness Use Case: Verifies the operational status of all configured expert services by calling their /ready endpoints. Returns an aggregated readiness status indicating whether the orchestrator can accept workflow requests.

5. Workflow Entity: A domain entity that maintains state machine semantics (PENDING → IN_PROGRESS → COMPLETED/FAILED) and encapsulates workflow steps with their associated expert calls.

6. Expert Gateway Port and HTTP Adapter (HttpExpertGateway): Defines the interface for invoking expert services and provides an HTTP implementation that supports both parallel (asyncio.gather) and sequential execution modes. The gateway handles HTTP communication, error handling, and result parsing.

7. Expert Readiness Gateway (HttpExpertReadinessGateway): Performs health checks against expert services by calling their /ready endpoints with fast timeouts and no retries to quickly detect unavailable services.

8. Expert Registry: Manages the mapping between expert identifiers and their service URLs. Expert URLs are configured via environment variables (e.g., EXPERT_ERYTHEMA_CLASSIFIER_URL). The registry provides methods to discover configured experts and resolve their URLs.

9. Result Mappers (DiagnosisResultMapper, SeverityResultMapper): Anti-corruption layer components that transform raw expert responses into the structured DiagnosisExpertResults and SeverityExpertResults output models. The mappers validate result completeness and handle per-image result correlation.

10. Dependency Injection Container: Manages the lifecycle of all application components using the dependency-injector library, including HTTP clients, gateways, mappers, and use cases.

SOUPs

The Expert Orchestrator directly uses the following SOUP items:

• FastAPI: Web framework for building the HTTP API endpoints.
• Uvicorn: ASGI server for running the FastAPI application.
• Pydantic and pydantic-settings: Data validation, serialization, and configuration management.
• dependency-injector: Dependency injection framework for managing component wiring and lifecycle.
• httpx: Asynchronous HTTP client for communication with expert services.
• legithp-interface-models: Shared data models for expert input/output contracts and workflow results.
• legithp-essentials: Shared utilities including the async HTTP client with retry logic and correlation ID support.

Interfaces with other software items

The Expert Orchestrator interfaces with the following software items:

• Control Plane: The Expert Orchestrator receives HTTP requests from the Control Plane at the /workflow/diagnosis and /workflow/severity endpoints, returning aggregated expert results.
• Expert Services: The Expert Orchestrator invokes individual expert services (condition classifier, sign classifiers, segmenters, detectors, image quality, image domain/modality) via HTTP to obtain analysis results. It manages parallel execution and result aggregation.
• legithp-interface-models: Provides the canonical data contracts (ExpertInput, MultiImageExpertInput, DiagnosisExpertResults, SeverityExpertResults) that define the interface between the orchestrator and its consumers/providers.

The following diagram depicts the Expert Orchestrator architecture and its relations with other software items.

Sign detection experts

Detection experts are specialized software items that perform object detection on medical images, identifying and localizing discrete clinical findings such as lesions, papules, or nodules. Each detection expert is deployed as an independent HTTP service that receives image data, executes a YOLO-based detection model, and returns structured results containing bounding boxes, confidence scores, and optional cropped regions for each detected object.

All detection experts share a common architecture built on the legithp-expert framework, with clear separation between application logic, domain entities, and infrastructure. The main software units are:

1. REST API layer (rest_app.py, server.py): Defines the FastAPI application factory and Uvicorn server entry point. It instantiates the inference model, registers prediction endpoints (e.g., /detect), and exposes standard operational endpoints (/health, /ready, /model/info, /system/info, /system/resources).

2. ExpertService (framework platform): A builder class provided by legithp-expert that assembles the FastAPI application with lifecycle management, model loading, health checks, and monitoring infrastructure. It receives an inference model implementation and handler functions for prediction endpoints.

3. Inference model adapter (YoloInferenceModel): Implements the InferenceModelPort interface and encapsulates loading, device management (CPU/GPU), and inference execution for a YOLO-based detection model. It preprocesses images (color-space conversion), invokes the underlying Ultralytics YOLO model, and returns raw detection results.

4. Object detector adapter (YoloObjectDetector): Implements the ObjectDetector protocol. It receives raw model outputs and converts them into domain DetectionCollection entities, handling both standard and oriented bounding boxes.

5. Detection use case (DetectObjectsUseCase): Orchestrates the end-to-end detection workflow: decoding the input image, invoking the object detector, optionally cropping detected regions, rendering an annotated visualization, and mapping domain detections to the interface output model (DetectionAssessment).

6. Rendering and cropping adapters (OpenCVBoundingBoxRenderer, AlwaysCropStrategy): Infrastructure components that draw bounding boxes on images and extract cropped sub-images for each detection.

7. Domain mapper (DomainDetectionMapper): An Anti-Corruption Layer adapter that converts domain detection entities to the shared legithp-interface-models output structures (DetectedObject, DetectionResult).

8. Dependency Injection container (DetectionContainer): Wires together all infrastructure adapters and application services using the dependency-injector library, enabling testability and configuration-driven composition.

9. Configuration (get_settings, DetectionSettings, YoloParameters): Loads service-level and model-level parameters from environment variables (via Pydantic Settings), including inference thresholds, cropping enablement, server host/port, and model weights location.

SOUPs

The detection expert relies on the following external libraries:

• FastAPI / Uvicorn – HTTP framework and ASGI server for exposing the REST API.
• Ultralytics (YOLO) – Provides the YOLO model loading, inference, and post-processing routines.
• PyTorch – Underlying deep-learning runtime for model execution.
• OpenCV (opencv-contrib-python-headless) – Image processing and rendering of annotated bounding boxes.
• NumPy / Pillow – Array manipulation and image I/O.
• Pydantic / Pydantic-Settings – Data validation and environment-based configuration.
• dependency-injector – Dependency injection container.
• httpx – HTTP client (used in test clients and for potential upstream calls).
• boto3 / azure-storage-blob – Cloud storage access for model weights (S3 or Azure Blob).

Interfaces with other software items

• Expert Orchestrator / Control Plane: The detection expert is invoked via its HTTP REST API (POST /detect) by the Expert Orchestrator or Control Plane, which supplies a base64-encoded clinical image and receives a DetectionAssessment response containing the list of detected objects, annotated image, and inference metadata.
• Shared data models (legithp-interface-models): Input (ExpertInput) and output (DetectionAssessment, DetectedObject, BoundingBox) types are defined in the shared library to ensure contract consistency across all experts and consumers.
• Model weights storage: At startup, the detection expert loads pre-trained YOLO weights from a configurable storage backend (local filesystem, AWS S3, or Azure Blob Storage) through the ModelWeightsProviderPort abstraction.
• Report builder: The DetectionAssessment output, including the annotated image and structured detections, may be forwarded to the Report builder for inclusion in patient-facing or clinician-facing reports.

The following diagram depicts the detection expert architecture and its relationships with other software items.

Sign segmentation experts

Segmentation experts produce pixel-level segmentation masks that quantify the spatial extent of clinical signs such as erythema, hyperpigmentation, or wound tissue types. Each segmenter receives an encoded image, executes a deep learning segmentation model, and returns probabilistic masks, binary masks, and coverage percentages.

All segmentation experts share a common architecture through the segmenter_base module and the legithp-expert framework. Each concrete instance (e.g., hyperpigmentation_segmenter, erythema_segmenter) differs only in its model weights and configuration.

The main software units are:

1. Entry point (main.py): Bootstraps the HTTP server by loading configuration settings and launching Uvicorn via the expert platform's server runner. It defines the host, port, and worker count for the service.

2. Application factory (app.py): Creates and configures the FastAPI application by invoking the shared factory from segmenter_base. It binds the segmenter-specific configuration (endpoint path, model weights location, segmentation label) to the generic service skeleton.

3. Configuration module (config.py): Provides segmenter-specific parameters such as the API endpoint path (e.g., /segmenter/hyperpigmentation), the S3 key for model weights, and the segmentation label used in output DTOs. Configuration is loaded from environment variables.

4. Segmenter factory (factory.py): Assembles the complete service by wiring the model adapter, prediction pipeline, use case, and prediction handler into a FastAPI application. It registers the prediction endpoint and attaches health-check and monitoring infrastructure provided by the platform.

5. Dependency injection container (composition.py): Configures all dependencies (model adapter, pipeline, image codec, mask renderer, domain-to-DTO mapper) using the dependency_injector library. The container is parameterized with model configuration and rendering style.

6. Model adapter (model.py): Wraps the neural network architecture (created via segmentation_models_pytorch) and integrates it with the platform's inference port. It handles device placement, weight loading, and health checks.

7. Prediction pipeline (pipeline.py): Implements the SegmentationPipelinePort interface. It preprocesses images (padding to square, resizing, normalization), invokes the model, and postprocesses outputs (sigmoid activation, resizing back to original dimensions, thresholding, percentage calculation).

8. Segment image use case (legithp-expert/modules/segmentation): Orchestrates the end-to-end prediction flow: image decoding, pipeline execution, mask rendering, and mapping of domain entities to the SegmentationAssessment interface DTO.

9. Request handler (handlers.py): Provides the curried handler function expected by the expert platform. It connects incoming HTTP requests to the segment image use case.

SOUPs

SOUPs and third-party libraries directly used by this software item include:

• PyTorch – Deep learning framework for model inference and tensor operations.
• segmentation-models-pytorch – Provides pre-built segmentation architectures (e.g., DeepLabV3+, U-Net++) and encoder backbones.
• torchvision – Image transformations (resizing) during preprocessing.
• OpenCV – Image manipulation for mask resizing and rendering.
• NumPy – Array operations for mask processing and percentage calculation.
• FastAPI – HTTP framework exposing the REST prediction endpoint.
• Uvicorn – ASGI server running the FastAPI application.
• Pydantic – Data validation and serialization for request/response models.
• dependency-injector – Dependency injection container for wiring components.

Interfaces with other software items

• Expert Orchestrator: Invokes the segmentation expert via HTTP POST requests to the prediction endpoint. The orchestrator passes an ExpertInput DTO containing a base64-encoded image and receives a SegmentationAssessment DTO with segmentation results.
• Report Builder: Consumes the SegmentationAssessment output (via the orchestrator) to extract SignExtent entities containing probabilistic masks, binary masks, and coverage percentages for inclusion in severity reports.
• Cloud Storage (S3 / Azure Blob): Model weights are retrieved from cloud storage at service startup. The storage adapter is configured via environment variables and managed by the expert platform's model weights provider.
• Expert Platform (legithp-expert): Provides the foundational infrastructure including the ExpertService builder, model loading lifecycle, health endpoints, and the segmentation module with domain entities, use cases, and rendering components.
• Interface Models (legithp-interface-models): Defines the canonical DTOs (ExpertInput, SegmentationAssessment, SegmentedObject) shared between the segmentation expert and its consumers.

The following diagram depicts the segmentation expert architecture and its relations with other software items.

Sign classification experts

Classification experts assess clinical signs by producing either a continuous severity score or a binary presence indicator from images. Each classifier is deployed as a standalone HTTP service, receiving a base64-encoded image and returning a structured assessment result.

Multiple classifier instances exist in the system—each targeting a specific clinical sign (e.g., crusting, desquamation, erythema, pustule)—but all share the same architecture through the classifier_base module. Classifiers support two output modes:

• Severity assessment: Returns a continuous score with an intensity label
• Presence assessment: Returns a binary indicator with confidence

The main software units are:

1. Application entry point and server runner (main.py): Bootstraps the HTTP server using the Uvicorn ASGI server. Reads environment-based configuration (host, port, number of workers) and launches the FastAPI application.

2. Application factory (app.py): Creates the FastAPI application instance by delegating to the shared create_classifier_service() factory. Configures logging and initializes the service with the classifier-specific configuration.

3. Configuration provider (config.py): Defines the classifier-specific parameters including the endpoint path, model weights location (S3 key), and model configuration (architecture, encoder backbone, number of classes, image size, classification label, postprocessing type). Each concrete classifier expert provides its own configuration pointing to its specific model.

4. Service factory (classifier_base.factory): Instantiates the dependency injection container, wires together model, pipeline, and use-case components, and registers the prediction endpoint on the FastAPI router. Returns a fully configured FastAPI application.

5. Dependency injection container (classifier_base.composition): Constructs and provides instances of the classification model adapter, classification pipeline, and classification use case, ensuring consistent dependency management throughout the request lifecycle.

6. Classification use case (classifier_base.application.handlers.ClassifyImageUseCase): Application-layer orchestrator that decodes incoming base64-encoded images via the image codec, invokes the classification pipeline, and serializes the result into the appropriate response model (SignSeverityAssessment for severity mode or SignPresenceAssessment for presence mode).

7. Prediction pipeline (classifier_base.infrastructure.ml.pipeline.ClassificationPipeline): Coordinates preprocessing, inference, and postprocessing. Preprocessing includes image padding (to square), resizing, and normalization. Postprocessing converts raw model logits to a severity score through configurable strategies (e.g., softmax-weighted mean, sigmoid, argmax).

8. Model architecture (classifier_base.infrastructure.ml.model.ClassificationModelArchitecture): Defines the neural network topology. Uses a pretrained encoder backbone (e.g., EfficientNet-B2) extracted from segmentation_models_pytorch, removes the decoder/segmentation head, and adds adaptive average pooling plus a fully connected classification layer. Handles ImageNet normalization internally.

9. Model adapter (classifier_base.infrastructure.ml.model.ClassificationModelAdapter): Platform adapter wrapping the raw PyTorch model. Extends PytorchModelAdapter and exposes predict() for synchronous inference and health_check() for startup validation.

10. Image codec (legithp-expert.modules.computer_vision.Base64ImageCodec): Decodes incoming base64-encoded image strings into an internal Image domain object suitable for further processing.

SOUPs

The classification expert directly uses the following third-party libraries:

• FastAPI / Uvicorn: Web framework and ASGI server providing the HTTP REST interface.
• Pydantic / pydantic-settings: Data validation and settings management via environment variables and typed configuration classes.
• PyTorch / torchvision: Deep-learning framework for model definition, tensor manipulation, and inference; torchvision provides image transformation utilities (resizing).
• segmentation-models-pytorch: Supplies pretrained encoder backbones used as feature extractors for classification.
• NumPy: Numerical array processing for padding and tensor conversion during preprocessing.
• Pillow (PIL): Image decoding and manipulation underpinning the base64-to-image conversion.
• dependency-injector: Dependency injection container for wiring application components.
• boto3: AWS SDK used for downloading model weights from S3 cloud storage at service startup.

Interfaces with other software items

The classification expert interacts with the following components:

• Expert Orchestrator: Invokes the classification expert over HTTP by posting ExpertInput payloads (containing a base64-encoded image) and receives SignSeverityAssessment or SignPresenceAssessment payloads with the computed assessment. The Orchestrator treats all classification experts uniformly through their standardized REST API.
• Model weights storage (AWS S3): At startup, the service retrieves pretrained model weights from S3 using the path specified in its configuration.
• Shared libraries (legithp-expert, legithp-interface-models): The classification expert depends on the expert core framework for infrastructure components (server lifecycle, model adapters, GPU management, configuration) and on interface models for input/output data contracts.

The following figure depicts the classification expert architecture and its relations with other software items.

Condition Classifier expert

The Condition Classifier expert is a specialized software item that performs multi-class skin condition classification for diagnosis support workflows. Unlike sign classifiers (which assess severity of individual clinical signs), the Condition Classifier analyzes one or more images of a skin condition and produces a probability distribution across skin condition categories. It is the primary expert invoked during diagnosis support requests.

The Condition Classifier supports both single-image and multi-image analysis (up to 5 images). For multi-image inputs, it performs per-image classification and then aggregates results into a study-level probability distribution. It also generates explainability outputs (GradCAM++ saliency maps) and computes clinical risk indicators for decision support.

The Condition Classifier software item follows a hexagonal (clean) architecture with clearly separated domain, application, and infrastructure layers. It comprises the following software units:

Infrastructure layer (inbound adapters):

1. REST API handlers: Expose two endpoints via FastAPI—/predict for single-image classification and /predict/multi for multi-image classification with aggregation. The handlers use an Anti-Corruption Layer (ACL) pattern with input/output mappers to translate between REST request/response schemas and application-layer DTOs.
2. Application entry point and server configuration: Bootstraps the HTTP server using the Uvicorn ASGI server. Reads environment-based configuration and launches the FastAPI application with the configured host, port, and worker count.

Application layer:

3. Single-image recognition use case (RecognizeSkinCondition): Orchestrates the classification workflow for a single image. It decodes the input image, invokes the classifier to obtain a probability distribution, computes risk indicators, optionally generates saliency maps for top predictions, and maps results to the output DTO. Accepts optional clinical context (sex, age category, body site).
4. Multi-image recognition use case (RecognizeMultiImageSkinCondition): Orchestrates classification for multiple images concurrently. It processes each image through the single-image workflow, then uses a DistributionAggregator to combine per-image probability distributions into a study-level result. The aggregated distribution is then used to compute study-level risk indicators.
5. Explainability service: Coordinates generation of saliency maps using GradCAM++ for the top-N predicted conditions, producing visual overlays that highlight image regions most influential to each prediction.
6. Port interfaces: Define abstract contracts for outbound adapters—SkinConditionClassifierPort for ML inference, ImageExplainerPort for saliency generation, and RiskMetadataRepository for loading risk indicator mappings.

Domain layer:

7. Probability distribution value object (ProbabilityDistribution): An immutable collection of condition-probability pairs that validates probabilities sum to approximately 1.0. Provides methods for sorting by probability, computing normalized Shannon entropy, and accessing top-N predictions.
8. Risk assessment value objects: RiskAssessment (collection of risk scores), RiskScore (indicator-value pair), and RiskIndicatorMapping (sparse mapping from conditions to risk indicators).
9. Risk calculator domain service: Computes clinical risk indicators from the probability distribution using vectorized matrix multiplication. Builds a dense indicator matrix from sparse condition-to-indicator mappings and multiplies by the probability vector to produce risk scores for malignancy, urgency, and other clinical indicators.
10. Distribution aggregator domain service: Aggregates multiple probability distributions into a single study-level distribution using configurable strategies (e.g., averaging).

Infrastructure layer (outbound adapters):

11. ML classifier adapter: Wraps the neural network model, handling device placement, preprocessing (padding, resizing, normalization), inference execution, and postprocessing (softmax activation). Returns a ProbabilityDistribution domain object.
12. Image explainer adapter: Implements GradCAM++ saliency map generation, producing visual overlays encoded as base64 images.
13. Dependency injection container: Wires together all infrastructure adapters and application services using the dependency-injector library.

SOUPs

The Condition Classifier expert directly uses the following third-party libraries:

• FastAPI / Uvicorn: Web framework and ASGI server providing the HTTP REST interface.
• PyTorch / torchvision: Deep-learning framework for model definition, tensor manipulation, and inference.
• timm (PyTorch Image Models): Provides pretrained encoder backbones and model architectures.
• NumPy: Numerical array processing for preprocessing and probability aggregation.
• Pillow (PIL): Image decoding and manipulation.
• Pydantic / pydantic-settings: Data validation and settings management.
• dependency-injector: Dependency injection container for wiring application components.
• boto3: AWS SDK used for downloading model weights from S3 at service startup.

Interfaces with other software items

The Condition Classifier expert interfaces with the following components:

• Expert Orchestrator: Invokes the Condition Classifier over HTTP. For single-image analysis, posts to /predict with a single base64-encoded image and optional clinical context. For multi-image analysis, posts to /predict/multi with up to 5 images. Responses include the probability distribution (with optional saliency maps for top predictions), entropy score, and computed risk indicators. For multi-image requests, the response includes both per-image results and aggregated study-level results.
• Model weights storage (AWS S3): At startup, the service retrieves pretrained model weights from S3 using the path specified in its configuration.
• Shared libraries (legithp-expert, legithp-interface-models): The Condition Classifier depends on the expert core framework for infrastructure components and on interface models for input/output data contracts.

The following diagram depicts the Condition Classifier expert architecture and its relationships with other software items.

Validation experts

Validation experts are specialized software items that assess image suitability before clinical analysis proceeds. They act as gatekeepers in the processing pipeline, ensuring that only appropriate images reach the clinical analysis experts. Two validation experts are deployed: Image Quality and Image Domain and Modality.

Both validation experts share the same architectural patterns as other experts in the system: they are deployed as independent HTTP services built on the legithp-expert framework, receive base64-encoded images, and return structured assessment results. Both follow a clean architecture with separated domain, application, and infrastructure layers.

Image Quality expert

The Image Quality expert assesses the technical quality of dermatological images before clinical analysis. It combines a CNN-based machine learning quality score with technical requirements validation to determine whether an image is acceptable for reliable clinical analysis.

The expert returns a quality score on a 1-10 scale with categorical interpretation, a set of technical requirement validation results, and an overall acceptability determination. An image is considered acceptable only if it passes both the ML-based quality scoring (score ≥ ACCEPTABLE threshold) and all technical requirements.

Quality score categories:

• BAD (1.0 – 2.8): Unacceptable quality
• POOR (2.8 – 4.6): Below acceptable threshold
• ACCEPTABLE (4.6 – 6.4): Minimum acceptable quality
• GOOD (6.4 – 8.2): Good quality
• EXCELLENT (8.2 – 10.0): Optimal quality

Technical requirements validated:

• Minimum image size (224×224 pixels)
• Normal aspect ratio (width/height ≤ 2.0)
• Color image (RGB with sufficient color variance)

The Image Quality expert comprises the following software units:

Domain layer:

1. Image quality result entity: Aggregate root combining the quality score and technical requirements into a single assessment result with an overall acceptability determination.
2. Quality score value object: Validated score in the range [1, 10] with methods for categorical interpretation.
3. Technical requirements value object: Three boolean validation results (minimum size, aspect ratio, color image).
4. Technical requirements service: Domain service that coordinates three specialized validators—minimum size validator, aspect ratio validator, and color image validator.

Application layer:

5. Predict image quality use case: Orchestrates the complete assessment workflow—decodes the input image, invokes technical requirements validation, obtains the ML-based quality score, combines results into the domain entity, and maps to the output DTO.
6. Quality assessor port: Abstract interface for the ML-based quality scoring adapter.

Infrastructure layer:

7. REST API handler: Exposes the /assess endpoint via FastAPI for receiving image quality assessment requests.
8. ML quality assessor adapter: Wraps the EfficientNet-B5 neural network. Performs preprocessing (resize to 416×416, ImageNet normalization), inference, and linear score calibration (slope: 1.773, intercept: 5.782) to produce the final quality score.
9. Image codec: Decodes base64-encoded input images.
10. Dependency injection container: Wires together all components using the dependency-injector library.

Image Domain and Modality expert

The Image Domain and Modality expert performs hierarchical classification to determine whether an image contains dermatological content (domain) and, if so, what type of imaging modality was used (clinical photograph vs. dermoscopy).

The expert uses a single 3-way classification model that outputs probabilities for three classes: non-dermatological, dermatological-clinical, and dermatological-dermoscopic. The domain is determined by comparing the sum of dermatological probabilities against the non-dermatological probability. Modality classification is only computed and returned when the image is classified as dermatological.

Classification outputs:

• Domain: DERMATOLOGICAL or NON_DERMATOLOGICAL (with confidence score)
• Modality: CLINICAL or DERMOSCOPIC (only present for dermatological images, with confidence normalized by dermatological probability)

The Image Domain and Modality expert comprises the following software units:

Domain layer:

1. Image classification result entity: Aggregate root combining domain classification with optional modality classification. Enforces invariant that dermatological images must have modality and non-dermatological images must not.
2. Classification probabilities value object: Contains the three raw probabilities from the model (non-dermatological, clinical, dermoscopic) with methods to derive domain and modality classifications.
3. Domain and modality classification entities: Represent the classified domain (DERMATOLOGICAL/NON_DERMATOLOGICAL) and modality (CLINICAL/DERMOSCOPIC) with their associated confidence scores.

Application layer:

4. Predict image domain modality use case: Orchestrates the classification workflow—decodes the input image, invokes the classifier to obtain raw probabilities, constructs the domain entity with derived classifications, and maps to the output DTO.
5. Image classifier port: Abstract interface for the ML-based classification adapter.

Infrastructure layer:

6. REST API handler: Exposes the /classify endpoint via FastAPI for receiving domain and modality classification requests.
7. ML image classifier adapter: Wraps the EfficientNet-B0 neural network. Performs preprocessing (resize to 224×224, ImageNet normalization), inference, and softmax activation to produce the 3-class probability distribution.
8. Image codec: Decodes base64-encoded input images.
9. Dependency injection container: Wires together all components using the dependency-injector library.

SOUPs

Both validation experts use the following third-party libraries:

• FastAPI / Uvicorn: Web framework and ASGI server for the HTTP REST interface.
• PyTorch: Deep-learning framework for model inference.
• timm (PyTorch Image Models): Provides the EfficientNet encoder architectures (B5 for quality, B0 for domain/modality).
• NumPy / Pillow: Image processing and array manipulation.
• Pydantic: Data validation and serialization.
• dependency-injector: Dependency injection container.
• boto3: AWS SDK for model weights retrieval from S3.

Interfaces with other software items

• Expert Orchestrator: Invokes validation experts during the initial phase of both diagnosis and severity workflows. The Image Quality expert is called at /assess and the Image Domain and Modality expert at /classify. If validation fails (image not acceptable or not dermatological), the workflow terminates with an appropriate error response before clinical analysis begins.
• Clinical experts: Validation experts run before clinical experts (Condition Classifier, sign classifiers, segmenters, detectors) to ensure only suitable images proceed to clinical analysis.
• Model weights storage (AWS S3): Both validation experts retrieve their model weights from S3 at startup.

The following diagram depicts the validation expert architecture.

Dynamic behavior

The previous sections described the system's static structure—its components and their relationships. This section illustrates how those components interact at runtime during typical clinical workflows. The sequence diagrams show the complete request lifecycle from authentication through report delivery.

Understanding these runtime interactions is essential for:

• Verifying that the architecture supports the required workflows
• Identifying performance-critical paths and potential bottlenecks

Diagnosis support request flow

The following sequence diagram shows the interactions when an integrator submits a diagnosis support request. The flow proceeds through two phases:

1. Authentication: The integrator obtains a JWT by presenting credentials
2. Analysis: The request flows through the processing pipeline (API Gateway → Control Plane → Expert Orchestrator → Experts → Report Builder) and returns a structured report

Severity assessment request flow

The severity assessment flow follows the same structural pattern as diagnosis support, but with key differences in expert invocation:

• The integrator specifies which sign experts to consult (classifiers, segmenters, detectors)
• The Expert Orchestrator invokes the requested experts
• The Report Builder assembles sign assessments rather than diagnostic hypotheses

The following sequence diagram illustrates this flow.

Architectural design rationale

Architecture is not merely a description of structure—it reflects deliberate decisions made to satisfy requirements and constraints. This section explains the key architectural decisions, the requirements that motivated them, and how they support the system's quality attributes and regulatory obligations.

Microservice architecture

The system uses a microservice architecture where each software item is deployed as an independent service. This decision was driven by several requirements:

Requirement	Architectural response
Independent scaling	Expert services have different computational demands (GPU for inference vs. CPU for orchestration). Separate services allow targeted resource allocation.
Technology heterogeneity	Different experts may require different ML frameworks or versions. Service isolation prevents dependency conflicts.
Deployment independence	New expert models can be deployed without affecting other components, supporting the iterative model improvement cycle.
Fault isolation	A failure in one expert does not cascade to the entire system; the orchestrator can handle partial failures gracefully.

Layered request processing

Requests flow through a defined sequence of layers: API Gateway → Control Plane → Expert Orchestrator → Experts → Report Builder. This layered approach provides:

• Separation of concerns: Authentication/authorization (API Gateway), workflow coordination (Control Plane), parallel execution (Expert Orchestrator), inference (Experts), and output formatting (Report Builder) are handled by specialized components.
• Testability: Each layer can be tested independently with mock dependencies.
• Auditability: The API Gateway captures all requests before any processing occurs, ensuring complete audit trails.

Shared libraries and framework

The legithp-expert framework and legithp-interface-models library enable code reuse across experts while maintaining interface consistency:

• Consistent expert structure: All experts follow the same application structure (entry point, factory, configuration, use case, pipeline), reducing cognitive load when developing or maintaining experts.
• Standardized data contracts: Interface models define canonical DTOs that are shared between producers and consumers, preventing integration errors.
• Infrastructure reuse: Common capabilities (health checks, model loading, GPU management, configuration) are implemented once in the framework.

Quality attributes

The architecture supports the following quality attributes, which align with the requirements identified in risk management and requirements analysis.

Performance

• Parallel expert execution: The Expert Orchestrator invokes multiple experts concurrently using asynchronous HTTP, minimizing total latency for severity assessments that require multiple sign evaluations.
• GPU-enabled inference: Experts can be deployed on GPU instances to accelerate model inference without affecting CPU-bound components.
• Persistent connections: HTTP clients maintain connection pools with retry logic and exponential backoff to handle transient failures efficiently.

Safety

• Modular validation: Each software item can be verified independently, enabling thorough testing of safety-critical components (e.g., expert inference logic).
• Well-defined interfaces: Typed data contracts (via Pydantic models) enforce input validation at each boundary, reducing the risk of data corruption.
• Immutable audit logs: Write-only access to audit storage ensures that system activity records cannot be tampered with.

Security

• Defense in depth: Multiple security layers protect the system—API authentication (JWT), network isolation (private subnets), IAM role-based access, and request signing.
• Minimal attack surface: Each service exposes only the endpoints required for its function; internal services are not directly accessible from outside the network.
• Credential management: No long-lived credentials are stored; all AWS access uses temporary credentials via IAM role assumption.

Maintainability

• Dependency injection: All services use the dependency-injector library to wire components, enabling easy substitution of implementations for testing or configuration changes.
• Configuration externalization: Service configuration is loaded from environment variables, allowing the same code to run in different environments without modification.
• Monorepo structure: All source code resides in a single repository with shared tooling, simplifying dependency management and cross-service refactoring.

SOUP integration strategy

SOUP components are selected based on:

1. Maturity and community support: Preference for widely-adopted libraries with active maintenance
2. License compatibility: Verification that licenses permit use in a medical device context
3. Security track record: Review of known vulnerabilities and responsiveness to security issues
4. API stability: Preference for libraries with stable interfaces to minimize upgrade disruption

Each SOUP is documented in the SOUP catalog with its version, purpose, and risk assessment. The modular architecture allows individual SOUP components to be upgraded or replaced without requiring changes to other software items.