# syt20/ai-powered-medical-report-simplifier architecture

> Architecture diagram of the GitHub repository syt20/ai-powered-medical-report-simplifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/syt20/ai-powered-medical-report-simplifier
- Repository: https://github.com/syt20/ai-powered-medical-report-simplifier

## Overview

##### Project type and purpose
- This is a backend-focused full-stack microservice (no separate UI) built with Python and FastAPI.
- It ingests scanned medical report images, runs OCR, then calls Google’s Gemini AI to structure and summarize test results.

##### File structure
- Top level:
- .env, requirements.txt, README.md – configuration and docs
- Data/ – sample input images
- app/ – application code
– main.py: FastAPI server entry point
– ocr.py: image preprocessing, Tesseract OCR, parsing, confidence scoring
– gemini_client.py: wraps calls to Google Gemini AI for structured extraction and summary
– models.py: Pydantic schemas for request/response models
- temp/ and outputs/ – folders for intermediate files and results

##### README for additional insights
- Processing pipeline described as:
Image Upload → Preprocessing → OCR Text Extraction → Data Filtering → AI Analysis → Structured Output
- Key technologies: FastAPI, Tesseract OCR, Google Gemini AI, Pydantic

##### Main components and numbered execution blocks

1. Client / API Gateway
- Receives HTTP POST /process-image
- Handles multipart/form-data upload

2. FastAPI Server (app/main.py)
- Validates request via Pydantic models (app/models.py)
- Orchestrates the pipeline

3. OCR Module (app/ocr.py)
3.1. Image Preprocessing (resizing, thresholding, denoising)
3.2. Tesseract OCR Text Extraction
3.3. Raw Text Parsing (extract lines, filter test entries)
3.4. Confidence Calculation

4. Gemini AI Client (app/gemini_client.py)
4.1. Structured Data Extraction (normalize test values into JSON)
4.2. Patient-Friendly Summary Generation
4.3. Medical Analysis (status: low/normal/high)

5. Data Models & Validation (app/models.py)
- Final Pydantic schemas for “step2”, “step3”, and “final” output

6. Response to Client
- Returns multi-stage JSON with steps 1–3 and combined “final”

- Tesseract OCR engine (local executable, configured via TESSERACT_CMD)
- Google Gemini API (requires GEMINI_API_KEY & MODEL)

##### Architectural patterns & design principles
- Modular separation: API layer, OCR layer, AI client layer, data validation layer
- Single responsibility per module
- Dependency injection of models into main controller
- External service abstraction (gemini_client)

- [ ] Number each block clearly (1, 2, 3.1, 3.2, …, 7)
- [ ] Indicate environment variables feeding into external services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Pipeline stages
    1["1. Client/API Gateway"]:::internal --> 2["2. FastAPI Server"]:::internal
    2 --> 3_1["3.1 Image Preprocessing"]:::internal
    3_1 --> 3_2["3.2 OCR Text Extraction"]:::internal
    3_2 --> 3_3["3.3 Raw Text Parsing"]:::internal
    3_3 --> 3_4["3.4 Confidence Calculation"]:::internal
    3_4 --> 4_1["4.1 Structured Data Extraction"]:::internal
    4_1 --> 4_2["4.2 Summary Generation"]:::internal
    4_2 --> 4_3["4.3 Medical Analysis"]:::internal
    4_3 --> 5["5. Data Models & Validation"]:::internal
    5 --> 6["6. Response to Client"]:::internal

    %% External dependencies
    Tesseract["Tesseract OCR Engine"]:::external
    Gemini["Google Gemini API"]:::external
    Env[".env"]:::config
    Req["requirements.txt"]:::config

    %% Dashed external calls
    3_2 -.->|"exec Tesseract"| Tesseract
    4_1 -.->|"call Gemini API"| Gemini
    2 -.->|"load vars"| Env
    2 -.->|"install deps"| Req

    %% Click Events
    click 1 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/main.py"
    click 2 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/main.py"
    click 3_1 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/ocr.py"
    click 3_2 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/ocr.py"
    click 3_3 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/ocr.py"
    click 3_4 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/ocr.py"
    click 4_1 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/gemini_client.py"
    click 4_2 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/gemini_client.py"
    click 4_3 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/gemini_client.py"
    click 5 "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/app/models.py"
    click Env "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/.env"
    click Req "https://github.com/syt20/ai-powered-medical-report-simplifier/blob/main/requirements.txt"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#21618C,stroke-width:2px
    classDef external fill:#D5F5E3,stroke:#239B56,stroke-width:2px,stroke-dasharray: 5 5
    classDef config fill:#F4F6F7,stroke:#7B7D7D,stroke-width:2px,stroke-dasharray: 2 2
```
