# shubhamm-sinha/medxplain-ai architecture

> Architecture diagram of the GitHub repository shubhamm-sinha/medxplain-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubhamm-sinha/medxplain-ai
- Repository: https://github.com/shubhamm-sinha/medxplain-ai

## Overview

MedXplain turns a user-selected medical PDF into a language-specific, structured explanation: the API validates and extracts the PDF, cleans its text, requests constrained JSON analysis from Groq, and parses the result. The UI presents summaries, findings, charts, advice, and clinician/map options; users can optionally email the briefing and restore a prior successful session. The README documents the nearby-clinician and email capabilities; source excerpts show the analysis and email orchestration, while some UI integrations are unsampled, so those links are marked unverified.

Main entry points: [`MedXplain-api/Controllers/ReportController.cs`](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Controllers/ReportController.cs) (Report controller), [`medxplain-ui/src/components/ReportResults.tsx`](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/ReportResults.tsx) (Results view), [`medxplain-ui/src/App.tsx`](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/App.tsx) (App workflow), [`MedXplain-api/Services/GroqService.cs`](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Services/GroqService.cs) (Groq client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["React experience"]
  node_app["App workflow<br/>[App.tsx]"]
  node_upload["Upload form<br/>[UploadForm.tsx]"]
  node_api_client["Report API client<br/>[reportApi.ts]"]
  node_results["Results view<br/>[ReportResults.tsx]"]
  node_summary["Executive summary"]
  node_findings["Findings and advice"]
  node_charts["Charts<br/>[GraphSection.tsx]"]
  node_nearby["Nearby clinicians"]
  node_geolocation["Geolocation<br/>[useGeolocation.ts]"]
  node_maps["Map links<br/>[mapsLinks.ts]"]
  node_report_types["Report schema<br/>[report.ts]"]
end

subgraph group_api["Analysis API"]
  node_controller["Report controller"]
  node_validator["PDF validation"]
  node_pdf["PDF extraction"]
  node_cleaner["Text cleaning"]
  node_language["Language handling<br/>[LanguageHelper.cs]"]
  node_parser["Response parsing"]
  node_response["Analysis response"]
end

subgraph group_ai["LLM analysis"]
  node_groq_service["Groq client<br/>[GroqService.cs]"]
  node_prompt["Prompt templates"]
end

subgraph group_delivery["Report delivery"]
  node_delivery_panel["Email delivery panel"]
  node_email_service["Email service<br/>[EmailService.cs]"]
  node_html_builder["Email report HTML"]
end

subgraph group_session["Session and location"]
  node_storage[("Session storage<br/>[reportStorage.ts]")]
end

node_user(("Report user"))
node_groq{{"Groq API"}}
node_smtp{{"SMTP server"}}
node_browser_store[("Browser local storage")]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_upload
node_app -->|"calls"| node_api_client
node_api_client -->|"HTTP requests"| node_controller
node_controller -->|"validates upload"| node_validator
node_controller -->|"normalizes language"| node_language
node_controller -->|"extracts text"| node_pdf
node_controller -->|"cleans text"| node_cleaner
node_controller -->|"requests analysis"| node_groq_service
node_groq_service -->|"gets template"| node_prompt
node_groq_service -->|"builds instructions"| node_language
node_groq_service -->|"sends prompt"| node_groq
node_controller -->|"parses response"| node_parser
node_parser -->|"populates"| node_response
node_controller -->|"sends report"| node_email_service
node_email_service -->|"builds attachment"| node_html_builder
node_email_service -->|"sends email"| node_smtp
node_app -->|"renders report"| node_results
node_results -->|"renders"| node_summary
node_results -->|"renders"| node_findings
node_results -->|"renders"| node_charts
node_results -->|"renders"| node_nearby
node_results -->|"renders"| node_delivery_panel
node_app -->|"saves and restores"| node_storage
node_storage -->|"reads and writes"| node_browser_store
node_nearby -.->|"uses location"| node_geolocation
node_nearby -.->|"creates map links"| node_maps
node_delivery_panel -.->|"requests email"| node_api_client

click node_app "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/App.tsx"
click node_upload "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/UploadForm.tsx"
click node_api_client "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/api/reportApi.ts"
click node_results "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/ReportResults.tsx"
click node_summary "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/ExecutiveSummaryCard.tsx"
click node_findings "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/FindingsSection.tsx"
click node_charts "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/GraphSection.tsx"
click node_nearby "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/NearbyDoctorsSection.tsx"
click node_geolocation "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/hooks/useGeolocation.ts"
click node_maps "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/utils/mapsLinks.ts"
click node_report_types "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/types/report.ts"
click node_controller "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Controllers/ReportController.cs"
click node_validator "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Helpers/PdfFileValidator.cs"
click node_pdf "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Services/PdfExtractionService.cs"
click node_cleaner "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Services/TextCleaningService.cs"
click node_language "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Helpers/LanguageHelper.cs"
click node_parser "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Helpers/MedicalAnalysisResponseParser.cs"
click node_response "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/DTOs/AnalyzeReportResponse.cs"
click node_groq_service "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Services/GroqService.cs"
click node_prompt "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Services/PromptTemplateService.cs"
click node_delivery_panel "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/ReportDeliveryPanel.tsx"
click node_email_service "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-api/Services/EmailService.cs"
click node_html_builder "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-api/Helpers/ReportHtmlBuilder.cs"
click node_storage "https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/utils/reportStorage.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_upload,node_api_client,node_results,node_summary,node_findings,node_charts,node_nearby,node_geolocation,node_maps,node_report_types,node_user toneBlue
class node_controller,node_validator,node_pdf,node_cleaner,node_language,node_parser,node_response,node_browser_store toneAmber
class node_groq_service,node_prompt,node_groq,node_smtp toneMint
class node_delivery_panel,node_email_service,node_html_builder toneRose
class node_storage toneIndigo
```

## Components

### React experience

- [App workflow](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/App.tsx): `medxplain-ui/src/App.tsx`
- [Upload form](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/UploadForm.tsx): `medxplain-ui/src/components/UploadForm.tsx`
- [Report API client](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/api/reportApi.ts): `medxplain-ui/src/api/reportApi.ts`
- [Results view](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/ReportResults.tsx): `medxplain-ui/src/components/ReportResults.tsx`
- [Executive summary](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/ExecutiveSummaryCard.tsx): `medxplain-ui/src/components/ExecutiveSummaryCard.tsx`
- [Findings and advice](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/FindingsSection.tsx): `medxplain-ui/src/components/FindingsSection.tsx`
- [Charts](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/GraphSection.tsx): `medxplain-ui/src/components/GraphSection.tsx`
- [Nearby clinicians](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/NearbyDoctorsSection.tsx): `medxplain-ui/src/components/NearbyDoctorsSection.tsx`
- [Geolocation](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/hooks/useGeolocation.ts): `medxplain-ui/src/hooks/useGeolocation.ts`
- [Map links](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/utils/mapsLinks.ts): `medxplain-ui/src/utils/mapsLinks.ts`
- [Report schema](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/types/report.ts): `medxplain-ui/src/types/report.ts`

### Analysis API

- [Report controller](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Controllers/ReportController.cs): `MedXplain-api/Controllers/ReportController.cs`
- [PDF validation](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Helpers/PdfFileValidator.cs): `MedXplain-api/Helpers/PdfFileValidator.cs`
- [PDF extraction](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Services/PdfExtractionService.cs): `MedXplain-api/Services/PdfExtractionService.cs`
- [Text cleaning](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Services/TextCleaningService.cs): `MedXplain-api/Services/TextCleaningService.cs`
- [Language handling](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Helpers/LanguageHelper.cs): `MedXplain-api/Helpers/LanguageHelper.cs`
- [Response parsing](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Helpers/MedicalAnalysisResponseParser.cs): `MedXplain-api/Helpers/MedicalAnalysisResponseParser.cs`
- [Analysis response](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/DTOs/AnalyzeReportResponse.cs): `MedXplain-api/DTOs/AnalyzeReportResponse.cs`

### LLM analysis

- [Groq client](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Services/GroqService.cs): `MedXplain-api/Services/GroqService.cs`
- [Prompt templates](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/MedXplain-api/Services/PromptTemplateService.cs): `MedXplain-api/Services/PromptTemplateService.cs`

### Report delivery

- [Email delivery panel](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/components/ReportDeliveryPanel.tsx): `medxplain-ui/src/components/ReportDeliveryPanel.tsx`
- [Email service](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-api/Services/EmailService.cs): `medxplain-api/Services/EmailService.cs`
- [Email report HTML](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-api/Helpers/ReportHtmlBuilder.cs): `medxplain-api/Helpers/ReportHtmlBuilder.cs`

### Session and location

- [Session storage](https://github.com/shubhamm-sinha/medxplain-ai/blob/master/medxplain-ui/src/utils/reportStorage.ts): `medxplain-ui/src/utils/reportStorage.ts`

### Other components

- **Report user**
- **Groq API**
- **SMTP server**
- **Browser local storage**

## Connections

- Report user → App workflow: uses (evidence: `README.md`)
- App workflow → Upload form: renders (evidence: `medxplain-ui/src/App.tsx`)
- App workflow → Report API client: calls (evidence: `medxplain-ui/src/App.tsx`)
- Report API client → Report controller: HTTP requests (evidence: `README.md`)
- Report controller → PDF validation: validates upload (evidence: `MedXplain-api/Controllers/ReportController.cs`)
- Report controller → Language handling: normalizes language (evidence: `MedXplain-api/Controllers/ReportController.cs`)
- Report controller → PDF extraction: extracts text (evidence: `MedXplain-api/Controllers/ReportController.cs`)
- Report controller → Text cleaning: cleans text (evidence: `MedXplain-api/Controllers/ReportController.cs`)
- Report controller → Groq client: requests analysis (evidence: `MedXplain-api/Controllers/ReportController.cs`)
- Groq client → Prompt templates: gets template (evidence: `MedXplain-api/Services/GroqService.cs`)
- Groq client → Language handling: builds instructions (evidence: `MedXplain-api/Services/GroqService.cs`)
- Groq client → Groq API: sends prompt (evidence: `MedXplain-api/Services/GroqService.cs`)
- Report controller → Response parsing: parses response (evidence: `MedXplain-api/Controllers/ReportController.cs`)
- Response parsing → Analysis response: populates (evidence: `MedXplain-api/Helpers/MedicalAnalysisResponseParser.cs`)
- Report controller → Email service: sends report (evidence: `MedXplain-api/Controllers/ReportController.cs`)
- Email service → Email report HTML: builds attachment (evidence: `medxplain-api/Services/EmailService.cs`)
- Email service → SMTP server: sends email (evidence: `medxplain-api/Services/EmailService.cs`)
- App workflow → Results view: renders report (evidence: `medxplain-ui/src/App.tsx`)
- Results view → Executive summary: renders (evidence: `medxplain-ui/src/components/ReportResults.tsx`)
- Results view → Findings and advice: renders (evidence: `medxplain-ui/src/components/ReportResults.tsx`)
- Results view → Charts: renders (evidence: `medxplain-ui/src/components/ReportResults.tsx`)
- Results view → Nearby clinicians: renders (evidence: `medxplain-ui/src/components/ReportResults.tsx`)
- Results view → Email delivery panel: renders (evidence: `medxplain-ui/src/components/ReportResults.tsx`)
- App workflow → Session storage: saves and restores (evidence: `medxplain-ui/src/App.tsx`)
- Session storage → Browser local storage: reads and writes (evidence: `medxplain-ui/src/utils/reportStorage.ts`)
- Nearby clinicians → Geolocation: uses location
- Nearby clinicians → Map links: creates map links
- Email delivery panel → Report API client: requests email
