MedMatrix Workspace Architecture

Electron Desktop Application

The user interface mimics a medical diagnostic screen, built on Electron (v29) running a React (v18) application with TypeScript.

Core Modules in App.tsx

The primary client controller coordinates four workstation states:

• Ingest Tab: Manages DICOM uploads and raw K-Space arrays. Connects to backend endpoints and triggers MinIO uploads.
• Archive/Studies Tab: Presents a tabular index of patient scans, process states (pending, processing, complete, failed), and metadata.
• Patients Tab: Integrates clinical detail sheets, medical history logs, and risk factors.
• AI Reports Tab: Renders structured diagnosis recommendations, pathology classification graphs (Recharts), and interactive 3D visualizations.

3D Volumetric Visualizations

To assist radiologists, the frontend integrates complex rendering libraries:

• Cornerstone3D: Core viewport for slicing raw DICOM files, mapping pixel coordinates, window/leveling, and medical annotations.
• Three.js / VTK.js: Renders a 3D polygonal volume reconstruct of the brain. Highlights predicted pathology locations as glowing nodes with corresponding bounding boxes computed by the spatial attention models.

/* Siemens Syngo style grid layout definition */
.syngo-layout {
  display: grid;
  grid-template-rows: 40px 1fr 24px;
  height: 100vh;
}
.bevel-inset {
  border: 2px solid;
  border-color: #8898a5 #ffffff #ffffff #8898a5;
}
.clinical-btn-primary {
  background: linear-gradient(to bottom, #e3eeeb, #ccdcd7);
  border-color: #799a8c;
  color: var(--color-accent-green);
  font-weight: bold;
}

Node.js / Express Backend & Worker

The Express backend acts as the data hub, mapping PostgreSQL models via Prisma ORM and running heavy background jobs via BullMQ + Redis.

Job Processing Pipeline

Heavy computation is isolated from the main HTTP loop. The components are structured as follows:

import { Worker, Job } from 'bullmq';
import { aiClient } from './ai-client';
import { prisma } from './db';

export const studyWorker = new Worker('study-processing', async (job: Job) => {
  const { studyId } = job.data;
  await prisma.study.update({ where: { id: studyId }, data: { status: 'processing' } });
  
  try {
    // Call Python/C++ FastAPI predictive cascade
    const aiResult = await aiClient.predictStudy(studyId);
    
    // Persist results in PostgreSQL
    await prisma.$transaction([
      prisma.modelResult.create({ data: { ... } }),
      prisma.study.update({ where: { id: studyId }, data: { status: 'complete' } })
    ]);
  } catch (err) {
    await prisma.study.update({ where: { id: studyId }, data: { status: 'failed' } });
  }
}, { connection: redisConn });

MinIO Object Storage

Manages binary asset storage. Utilizes two S3 buckets: kspace-raw for uploaded numpy kspace matrices/DICOM files, and reconstructed-magnitude for the final parsed magnitude slices.

Python AI Service (FastAPI)

The AI service runs as a FastAPI microservice containing reconstruction pipelines, PyTorch neural networks, and model training routines.

Phase 2 Two-Tier Gating Flow

To optimize CUDA memory, the application implements a cascading gateway mechanism before running the volumetric spatial classifier:

Volumetric Fused S4-CNN Architecture

The production classification model (fused_model_128.onnx) uses a dual-branch encoder that fuses raw frequency acquisitions with spatial magnitude images:

• Frequency Branch: Diagonal Continuous State Space Model (S4D) layers map raw flat K-space sequence data. It tracks phase encoding paths across 8 sequential slices in the complex frequency domain.
• Spatial Branch: Parameter-efficient Conv2D convolutions evaluate the magnitude reconstructions. Adaptive average pooling compresses spatial activations to a 128-dimensional latent vector.
• Slice Cross-Attention: The spatial query vectors interact with the frequency key/value vectors, generating a joint representation pooled for logit mapping.

C++ Inference Engine & ONNX Runtime

For high-throughput diagnostic execution, model files are loaded by a C++ inference library (ai-service/inference/) compiled with ONNX Runtime v1.24.4.

Features & Performance

• CUDA Acceleration: Attempts to initialize the CUDA Execution Provider. Fallback to CPU execution is automatically handled on devices without discrete NVIDIA GPUs.
• Memory Binding: Binds raw input pointers directly to CPU/GPU buffers using Ort::Value::CreateTensor to avoid redundant copies of volumetric tensors.
• Softmax Post-processing: Computes numerically stable softmax directly in C++ before packing results.
• Multi-threading Control: Limits intra-op threads to 1 or 2 threads to prevent CPU spinlock thread thrashing under concurrent WebWorker schedules.

Throughput Statistics

C++ Engine API Definition

#pragma once

#include <memory>
#include <string>
#include <vector>
#include <array>

namespace kvision {

/// Pathology class labels (11 classes matching training)
enum class Pathology : int {
    Normal                  = 0,
    Tumor_Glioma            = 1,
    Ischemia                = 2,
    MS_Lesions              = 3,
    Hydrocephalus           = 4,
    Atrophy                 = 5,
    Hemorrhage              = 6,
    Cerebral_Cyst           = 7,
    Edema                   = 8,
    AVM                     = 9,
    Cerebral_Microbleeds    = 10
};

struct InferenceResult {
    Pathology predicted_class;
    float     confidence;
    std::array<float, 11> logits;
    std::array<float, 11> probabilities;
    double    inference_time_ms;
};

class InferenceEngine {
public:
    explicit InferenceEngine(const InferenceConfig& config);
    ~InferenceEngine();

    InferenceResult infer(const std::vector<float>& kspace_data);
    InferenceResult infer(const float* kspace_data, size_t num_elements);
};

} // namespace kvision

Database Schema

Relational tables stored in PostgreSQL and mapped via Prisma. Focuses on patient archiving and AI gating checkpoints:

Interactive MRI Pipeline Simulator

Adjust variables and trigger the dual-stage processing workflow. This runs a mathematical mockup mimicking the gating threshold equations, denoiser activation, and final volumetric pathology classifier logits.