Skip to Content
Architecture

DermaDetect Platform Architecture

System Overview

The DermaDetect platform is a comprehensive dermatological diagnosis system that combines AI/ML-powered analysis with physician oversight. The system serves three main user groups:

  1. Patients - Submit skin condition cases via mobile/web apps
  2. Physicians - Review cases and provide diagnoses via backoffice portal
  3. Healthcare Partners - Integration partners (Maccabi, Miilabs, etc.) via APIs

High-Level Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         Client Applications                          │
├─────────────────┬─────────────────┬─────────────────────────────────┤
│ Mobile Apps     │ Web Portals     │ Healthcare Systems               │
│ (React Native)  │ (Next.js)       │ (Maccabi API Integration)        │
└────────┬────────┴────────┬────────┴─────────┬───────────────────────┘
         │                 │                  │
         └─────────────────┼──────────────────┘
                           │
         ┌─────────────────▼─────────────────┐
         │     API Gateway Service            │
         │  (FastAPI - Multi-tenant Auth)     │
         │                                    │
         │  - Authentication & Authorization  │
         │  - Case Management                 │
         │  - Image Upload/Storage            │
         │  - AI Service Orchestration        │
         └──┬──────────────┬─────────────┬────┘
            │              │             │
            │ HTTP         │ asyncpg     │ Azure SDK / GCS SDK
            │              │             │
    ┌───────▼───────┐  ┌───▼──────┐  ┌─▼─────────────────────┐
    │  AI Service   │  │PostgreSQL│  │   Cloud Storage        │
    │   (FastAPI)   │  │ Database │  │ (Azure Blob / GCS)     │
    │               │  │          │  │                        │
    │ - Diagnosis   │  │ - Cases  │  │ - Patient Images       │
    │ - Image QA    │  │ - Users  │  │ - Generated Reports    │
    │ - Triage      │  │ - Annot. │  │                        │
    │ - Questions   │  │ - Templ. │  │ (AI Service stores     │
    │               │  │          │  │  ML models locally)    │
    └───────────────┘  └──────────┘  └────────────────────────┘

Service Architecture

1. API Gateway Service

Responsibility: Unified API gateway providing authentication, multi-tenancy, and business logic orchestration

Key Components:

  • Authentication Module: JWT-based auth, session management, SAML/SSO
  • Multi-Tenancy Module: Tenant isolation, request counting, rate limiting
  • Patient API: Case submission, image upload, case status
  • Physician API: Case management, annotations, templates
  • Mobile API: Maccabi-specific mobile endpoints
  • Backoffice API: Administrative functions, batch operations

Port: 8000 (default)

Technology:

  • FastAPI with Pydantic validation
  • SQLAlchemy 2.0 (async)
  • asyncpg for PostgreSQL
  • JWT with python-jose
  • Azure/GCS/Firebase SDK for storage

API Structure:

/api/
  /v1/
    /auth/              # Authentication & authorization
    /ai/                # Proxy to AI service
    /cases/             # Case management
    /annotations/       # Physician annotations
    /templates/         # Diagnosis templates
    /images/            # Image upload/download
    /reports/           # PDF generation
    /mobile/            # Mobile-specific endpoints
    /backoffice/        # Admin endpoints

2. AI Service

Responsibility: Machine learning and AI-powered dermatological analysis

Key Components:

  • Diagnostics Module: Disease prediction from anamnesis
  • Image Quality Module: Validate image suitability
  • Red Flags Module: Identify urgent conditions
  • Next Question Module: Adaptive questionnaire management
  • Triage Module: Patient urgency assessment
  • Medical Supervisor: Rule-based post-processing

Port: 8080 (default)

Technology:

  • FastAPI with Pydantic validation
  • TensorFlow / Scikit-learn (ML models)
  • OpenCV (image processing)
  • NumPy / Pandas (data processing)
  • Azure Blob / GCS for model storage

API Structure:

/ai/
  /v1/
    /diagnosis/predict           # Main diagnosis prediction
    /diagnosis/red_flags         # Urgent condition detection
    /diagnosis/triage            # Patient triage
    /image_quality/validate      # Image quality assessment
    /questionnaire/next          # Get next question
    /internal/format_anamnesis   # Convert API format to internal

3. Shared Core Package (py_core)

Responsibility: Shared utilities and database layer

Modules:

  • db/ - Database connection and session management
  • repositories/ - Data access layer
  • models/ - Pydantic models for all entities
  • auth/ - Authentication utilities (JWT, password hashing)
  • logging_config.py - Structured logging setup
  • storage/ - S3/Azure/GCS abstractions
  • utils/ - Common utilities

Data Flow

Patient Case Submission Flow

1. Patient Opens Mobile App
   └─> POST /api/v1/auth/login (API Gateway)
       └─> Validates credentials, returns JWT

2. Patient Fills Questionnaire
   └─> POST /api/v1/ai/questionnaire/next (API Gateway → AI Service)
       └─> Returns next question based on answers
       └─> Repeat until complete

3. Patient Uploads Images
   └─> POST /api/v1/images/upload (API Gateway)
       └─> Validates image, uploads to cloud storage
       └─> Returns cloud path

4. Patient Submits Case
   └─> POST /api/v1/cases/submit (API Gateway)
       ├─> Validates request
       ├─> Calls AI Service for preliminary analysis
       │   └─> POST /ai/v1/diagnosis/predict (AI Service)
       │       └─> Returns disease probabilities
       ├─> Calls AI Service for red flags
       │   └─> POST /ai/v1/diagnosis/red_flags (AI Service)
       │       └─> Returns urgent conditions
       ├─> Calls AI Service for triage
       │   └─> POST /ai/v1/diagnosis/triage (AI Service)
       │       └─> Returns urgency level
       ├─> Assigns priority and private pool
       ├─> Saves case to database
       └─> Returns case UUID

5. System Routes Case to Physician
   └─> Based on priority, private_pool, and physician availability

Physician Diagnosis Flow

1. Physician Logs In
   └─> POST /api/v1/auth/login (API Gateway)
       └─> Validates credentials, returns JWT + session

2. Physician Requests Next Case
   └─> POST /api/v1/backoffice/next-case (API Gateway)
       ├─> Checks physician's private pool
       ├─> Checks physician availability (vacation mode)
       ├─> Finds highest priority unassigned case
       ├─> Assigns case to physician (status → in_process)
       └─> Returns case details with AI suggestions

3. Physician Reviews Case
   └─> GET /api/v1/cases/:uuid (API Gateway)
       ├─> Validates physician has access
       ├─> Fetches case details
       ├─> Fetches images from cloud storage
       └─> Returns complete case data

4. Physician Creates Diagnosis
   └─> POST /api/v1/annotations/:uuid (API Gateway)
       ├─> Validates physician owns case
       ├─> Saves annotation to database
       ├─> Updates case status → diagnosed
       ├─> Triggers patient notification
       └─> Returns success

5. Patient Views Diagnosis
   └─> GET /api/v1/cases/:uuid (API Gateway)
       ├─> Updates case status → viewed_by_patient
       └─> Returns diagnosis with recommendations

Database Schema

Core Tables

tenants - Multi-tenant support

  • id (PK)
  • name
  • url
  • api_key
  • settings (JSONB)

users - Patient accounts

  • uuid (PK)
  • email
  • password_hash
  • tenant_id (FK)
  • request_count
  • role
  • created_at

physicians - Physician accounts

  • uuid (PK)
  • email
  • password_hash
  • language_preference
  • private_pool
  • vacation_mode
  • active
  • created_at

rn_requests (cases) - Patient cases

  • uuid (PK)
  • status (0=created, 1=complete, 2=in_process, 3=diagnosed, 4=viewed)
  • vendor_id
  • tenant_id (FK)
  • user_identifier
  • created_by (FK to users)
  • assigned_to (FK to physicians)
  • priority
  • private_pool
  • header (JSONB - metadata)
  • request (JSONB - patient anamnesis)
  • ml_result (JSONB - AI predictions)
  • internal_request (JSONB - formatted for AI)
  • created_at
  • modified_at
  • diagnosed_at
  • viewed_at

dermatologist_annotation - Physician diagnoses

  • uuid (PK)
  • case_uuid (FK to rn_requests)
  • physician_uuid (FK to physicians)
  • disease_id
  • text (diagnosis notes)
  • treatment_recommendation
  • created_at
  • modified_at
  • status (active, cancelled)

diseases - Disease master list

  • id (PK)
  • name_en
  • name_he
  • vendor_id
  • severity_level

templates - Physician diagnosis templates

  • id (PK)
  • physician_uuid (FK)
  • disease_id (FK)
  • text
  • created_at

service_log - API call logging

  • uuid (PK)
  • service_name
  • user_email
  • tenant_id (FK)
  • response_status
  • created_at

audit_annotation - Audit trail

  • uuid (PK)
  • case_uuid (FK)
  • physician_uuid (FK)
  • action
  • old_status
  • new_status
  • created_at

Authentication & Authorization

Authentication Methods

  1. Local Authentication (Email/Password)

    • Bcrypt password hashing
    • JWT token generation
    • Token expiration: 1 hour (configurable)

  2. SAML/SSO (Enterprise)

    • SAML 2.0 protocol
    • Active Directory integration
    • Automatic user provisioning

  3. Maccabi Integration (Healthcare Partner)

    • Maccabi API token validation
    • OAuth-like token exchange
    • Technical ID-based lookup

Authorization Model

Roles:

  • patient - Can submit cases, view own cases
  • physician - Can review cases, create annotations
  • superuser - Full administrative access
  • readonly - Limited read-only access

Multi-Tenancy:

  • All data isolated by tenant_id
  • Users can only access data within their tenant
  • API key required for tenant access (API routes)

Request Counting:

  • Each user has request_count (default: 500)
  • Decremented on each API call
  • Superusers have unlimited requests
  • Demo users (tenant_id=1) require special header

Cloud Storage Strategy

The system supports multiple cloud storage providers:

Azure Blob Storage:

  • Primary for Maccabi deployments
  • Connection string in environment
  • Containers: dermadetect, myderma, resources

Google Cloud Storage (GCS):

  • Primary for general deployments
  • Service account authentication
  • Buckets: dermadetect-images, dermadetect-models

Firebase Storage:

  • Legacy support
  • Used by older mobile apps
  • Path structure: 000RN/{uuid}.{ext}

Scalability Considerations

Horizontal Scaling

  • Both API Gateway and AI Service are stateless
  • Can scale independently based on load
  • Load balancer distributes requests

Database Scaling

  • PostgreSQL with connection pooling
  • Read replicas for reporting queries
  • Partitioning by tenant_id for large datasets

Caching Strategy

  • Redis for session storage (future)
  • In-memory caching for disease lists
  • CDN for static resources

Async Processing

  • All database operations are async (asyncpg)
  • HTTP calls to AI service are async (httpx)
  • Image uploads are async

Monitoring & Observability

Logging

  • Structured logging with structlog
  • JSON format for production
  • Request ID tracking across services
  • Log levels: DEBUG, INFO, WARNING, ERROR

Metrics

  • Prometheus metrics endpoint
  • Request count, latency, errors
  • Custom business metrics (cases per hour, etc.)

Health Checks

  • /healthy endpoint on each service
  • Database connectivity check
  • External service health (AI, storage)

Security Considerations

API Security

  • JWT token validation on all protected routes
  • CSRF protection for web clients
  • Rate limiting (60 req/min global)
  • Input validation with Pydantic
  • SQL injection prevention (parameterized queries)

Data Security

  • Passwords hashed with bcrypt (cost: 10)
  • HTTPS required in production
  • Secrets in environment variables
  • PII data encrypted at rest (database-level)

HIPAA/GDPR Compliance

  • Audit logging for all data access
  • Data deletion endpoint (/delete_user)
  • Patient consent tracking
  • Data retention policies

Deployment Architecture

Development Environment

Docker Compose
├── PostgreSQL (port 5432)
├── API Gateway (port 8000)
├── AI Service (port 8080)
└── LocalStack (optional, for S3 testing)

Production Environment

Kubernetes Cluster
├── API Gateway Deployment (3+ replicas)
│   ├── Ingress (HTTPS)
│   └── Service (LoadBalancer)
├── AI Service Deployment (2+ replicas)
│   └── Service (ClusterIP)
├── PostgreSQL (Managed RDS/CloudSQL)
├── Redis (ElastiCache/MemoryStore)
└── Cloud Storage (Azure/GCS)

Migration Path

The backend_2025 consolidates:

  1. algo_python → services/ai_service/

    • Flask → FastAPI conversion
    • Preserve all ML/AI logic
    • Add async I/O

  2. dd_api → services/api_gateway/src/api/patient/

    • NestJS → FastAPI conversion
    • Prisma → SQLAlchemy conversion
    • Add async database operations

  3. api-mobile-maccabi → services/api_gateway/src/api/mobile/

    • NestJS → FastAPI conversion
    • TypeORM → SQLAlchemy conversion
    • Integrate Maccabi-specific endpoints

  4. api-backoffice-maccabi → services/api_gateway/src/api/backoffice/

    • NestJS → FastAPI conversion
    • TypeORM → SQLAlchemy conversion
    • Preserve physician workflow

Future Enhancements

  • Real-time Updates: WebSocket support for case status
  • Batch Processing: Async task queue (Celery) for bulk operations
  • ML Pipeline: Automated model retraining and deployment
  • Analytics: Data warehouse integration
  • Mobile SDK: Client SDKs for easier integration
  • GraphQL: Alternative API interface
Last updated on
Getting StartedAPI Gateway Service