# inkithai/ygc architecture

> Architecture diagram of the GitHub repository inkithai/ygc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/inkithai/ygc
- Repository: https://github.com/inkithai/ygc

## Overview

#### Purpose and entry points
This is a clinical-report analysis platform: users upload medical documents, receive evidence-backed extraction/review, and ask report-scoped questions. It comprises a React dashboard, a Node.js application API, and a Python RAG/clinical-processing service.
- `medreport_dashboard/src/main.jsx`
- `Backend/index.js`
- `rag_model/rag_api.py`

#### Web client and user workflow
The Vite/React dashboard owns browser routing, authentication state, API setup, report upload/review, report history, and chat presentation. It is a consumer of backend/service APIs rather than the clinical decision engine. Protected routes and auth context form the frontend access boundary.
- `medreport_dashboard/src/Routes.jsx`
- `medreport_dashboard/src/contexts/AuthContext.jsx`
- `medreport_dashboard/src/pages/upload-report/index.jsx`

#### Application API and identity boundary
The Node.js backend is the primary application-facing HTTP layer. Route modules separate user, chat, report, and demo capabilities; controllers implement request orchestration. Authentication and security middleware protect API access before controller execution. User/chat/report persistence is modeled separately in MongoDB-oriented models.
- `Backend/routes/userRoutes.js`
- `Backend/routes/chatRoutes.js`
- `Backend/middleware/auth.js`
- `Backend/models/reportModel.js`

#### Document ingestion and extraction
The Python service turns source documents into structured clinical data. The extraction subsystem includes preprocessing, OCR, quality assessment, parsing, text fallback, vision fallback, original-file handling, and queued jobs. This is the critical boundary between untrusted PDFs/images and downstream clinical reasoning; extracted evidence and provenance must remain linked to source pages/files.
- `rag_model/extraction/parser.py`
- `rag_model/extraction/ocr.py`
- `rag_model/extraction/ocr_quality.py`
- `rag_model/clinical_extraction.py`

#### Clinical reasoning and safety pipeline
Structured facts flow through a clinical pipeline that resolves patient context, builds a patient graph, applies clinical rules/derivations, performs risk classification, and produces citation-aware, policy-constrained answers. Static medical datasets support drug interactions, dose limits, LOINC mapping, trends, and specialist modules. Safety, input-safety, confidence, validation, and self-consistency modules constrain behavior and support abstention/fallbacks rather than unsupported answers.
- `rag_model/core/pipeline.py`
- `rag_model/core/patient_graph.py`
- `rag_model/core/clinical_review.py`
- `rag_model/response_validator.py`
- `rag_model/data/drug_interactions.json`

#### Conversational and report outputs
Chat logic detects intent, builds report/patient context, maintains follow-up state, and selects response builders. Evidence presentation in the UI renders PDF pages and overlays source locations, providing the user-facing provenance boundary. The service can also generate PDF outputs.
- `rag_model/chat/context_builder.py`
- `rag_model/chat/intent_detector.py`
- `rag_model/chat/response_builders.py`
- `medreport_dashboard/src/components/evidence/SourcePageViewer.jsx`
- `rag_model/pdf_generator.py`

#### Storage, services, and deployment
MongoDB is the material persistence layer across the Node backend and Python clinical/history stores. The Python side also integrates an LLM client and MedlinePlus knowledge client; these are external-service boundaries requiring degradation-safe behavior. Docker Compose supports the multi-service deployment, while Oracle deployment uses Compose plus Caddy; the frontend has container and Vercel deployment definitions.
- `Backend/db/index.js`
- `rag_model/clinical_store_mongo.py`
- `rag_model/core/groq_client.py`
- `rag_model/medlineplus_client.py`
- `docker-compose.yml`
- `deploy/oracle/docker-compose.oracle.yml`

Main entry points: [`rag_model/rag_api.py`](https://github.com/inkithai/ygc/blob/main/rag_model/rag_api.py) (Clinical service API), [`rag_model/response_validator.py`](https://github.com/inkithai/ygc/blob/main/rag_model/response_validator.py) (Safety & response validation), [`docker-compose.yml`](https://github.com/inkithai/ygc/blob/main/docker-compose.yml) (Compose deployment), [`medreport_dashboard/src/pages/upload-report/index.jsx`](https://github.com/inkithai/ygc/blob/main/medreport_dashboard/src/pages/upload-report/index.jsx) (Upload & review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Dashboard"]
  node_dashboard["Dashboard entry<br/>React/Vite app<br/>[main.jsx]"]
  node_frontend_access["Routes &amp; auth<br/>access boundary<br/>[Routes.jsx]"]
  node_upload_review["Upload &amp; review<br/>report workflow<br/>[index.jsx]"]
  node_evidence_viewer["Evidence viewer<br/>provenance UI"]
end

subgraph group_api["Application API"]
  node_node_api["Node application API<br/>Node.js HTTP API<br/>[index.js]"]
  node_auth_middleware{{"Auth middleware<br/>security boundary<br/>[auth.js]"}}
  node_api_routes["User, chat &amp; report routes<br/>route modules<br/>[chatRoutes.js]"]
  node_report_model["Report model<br/>MongoDB model<br/>[reportModel.js]"]
end

subgraph group_clinical["Clinical Processing Service"]
  node_rag_api["Clinical service API<br/>Python RAG API<br/>[rag_api.py]"]
  node_document_extraction["Document extraction<br/>ingestion pipeline<br/>[parser.py]"]
  node_clinical_facts["Clinical fact extraction<br/>structured extraction"]
  node_clinical_pipeline["Clinical pipeline<br/>reasoning orchestration<br/>[pipeline.py]"]
  node_patient_graph["Patient graph<br/>clinical context graph<br/>[patient_graph.py]"]
  node_clinical_review["Clinical review &amp; risk<br/>rules and risk review<br/>[clinical_review.py]"]
  node_response_validation{{"Safety &amp; response validation<br/>answer safety boundary"}}
  node_chat_context["Chat context &amp; intent<br/>conversation orchestration<br/>[context_builder.py]"]
  node_pdf_output["PDF output generator<br/>report output<br/>[pdf_generator.py]"]
  node_clinical_datasets["Clinical datasets<br/>medical reference data"]
end

node_mongodb[("MongoDB<br/>persistence<br/>[index.js]")]
node_llm_client{{"LLM client<br/>external AI service<br/>[groq_client.py]"}}
node_medlineplus{{"MedlinePlus client<br/>external knowledge service"}}
node_compose_deployment["Compose deployment<br/>multi-service deployment<br/>[docker-compose.yml]"]

node_dashboard -->|"initializes"| node_frontend_access
node_frontend_access -->|"authorizes"| node_upload_review
node_upload_review -->|"uploads and queries"| node_node_api
node_upload_review -->|"reviews evidence"| node_evidence_viewer
node_node_api -->|"protects requests"| node_auth_middleware
node_auth_middleware -->|"permits authenticated requests"| node_api_routes
node_api_routes -->|"persists report records"| node_report_model
node_report_model -->|"stores"| node_mongodb
node_api_routes -->|"orchestrates clinical work"| node_rag_api
node_rag_api -->|"ingests documents"| node_document_extraction
node_document_extraction -->|"produces provenance-linked text"| node_clinical_facts
node_clinical_facts -->|"supplies structured facts"| node_clinical_pipeline
node_clinical_pipeline -->|"builds patient context"| node_patient_graph
node_patient_graph -->|"supports review"| node_clinical_review
node_clinical_datasets -->|"supplies medical rules and references"| node_clinical_review
node_clinical_review -->|"produces assessed findings"| node_response_validation
node_rag_api -->|"handles report questions"| node_chat_context
node_chat_context -->|"provides intent and context"| node_clinical_pipeline
node_response_validation -->|"uses constrained generation"| node_llm_client
node_response_validation -.->|"uses external knowledge"| node_medlineplus
node_response_validation -->|"generates validated output"| node_pdf_output
node_rag_api -->|"stores clinical history"| node_mongodb
node_document_extraction -->|"returns source locations"| node_evidence_viewer
node_compose_deployment -.->|"deploys"| node_node_api
node_compose_deployment -.->|"deploys"| node_rag_api
node_compose_deployment -.->|"deploys"| node_mongodb

click node_dashboard "https://github.com/inkithai/ygc/blob/main/medreport_dashboard/src/main.jsx"
click node_frontend_access "https://github.com/inkithai/ygc/blob/main/medreport_dashboard/src/Routes.jsx"
click node_upload_review "https://github.com/inkithai/ygc/blob/main/medreport_dashboard/src/pages/upload-report/index.jsx"
click node_evidence_viewer "https://github.com/inkithai/ygc/blob/main/medreport_dashboard/src/components/evidence/SourcePageViewer.jsx"
click node_node_api "https://github.com/inkithai/ygc/blob/main/Backend/index.js"
click node_auth_middleware "https://github.com/inkithai/ygc/blob/main/Backend/middleware/auth.js"
click node_api_routes "https://github.com/inkithai/ygc/blob/main/Backend/routes/chatRoutes.js"
click node_report_model "https://github.com/inkithai/ygc/blob/main/Backend/models/reportModel.js"
click node_rag_api "https://github.com/inkithai/ygc/blob/main/rag_model/rag_api.py"
click node_document_extraction "https://github.com/inkithai/ygc/blob/main/rag_model/extraction/parser.py"
click node_clinical_facts "https://github.com/inkithai/ygc/blob/main/rag_model/clinical_extraction.py"
click node_clinical_pipeline "https://github.com/inkithai/ygc/blob/main/rag_model/core/pipeline.py"
click node_patient_graph "https://github.com/inkithai/ygc/blob/main/rag_model/core/patient_graph.py"
click node_clinical_review "https://github.com/inkithai/ygc/blob/main/rag_model/core/clinical_review.py"
click node_response_validation "https://github.com/inkithai/ygc/blob/main/rag_model/response_validator.py"
click node_chat_context "https://github.com/inkithai/ygc/blob/main/rag_model/chat/context_builder.py"
click node_pdf_output "https://github.com/inkithai/ygc/blob/main/rag_model/pdf_generator.py"
click node_mongodb "https://github.com/inkithai/ygc/blob/main/Backend/db/index.js"
click node_llm_client "https://github.com/inkithai/ygc/blob/main/rag_model/core/groq_client.py"
click node_medlineplus "https://github.com/inkithai/ygc/blob/main/rag_model/medlineplus_client.py"
click node_clinical_datasets "https://github.com/inkithai/ygc/blob/main/rag_model/data/drug_interactions.json"
click node_compose_deployment "https://github.com/inkithai/ygc/blob/main/docker-compose.yml"

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_dashboard,node_frontend_access,node_upload_review,node_evidence_viewer toneBlue
class node_node_api,node_auth_middleware,node_api_routes,node_report_model toneAmber
class node_rag_api,node_document_extraction,node_clinical_facts,node_clinical_pipeline,node_patient_graph,node_clinical_review,node_response_validation,node_chat_context,node_pdf_output,node_clinical_datasets toneMint
class node_mongodb,node_llm_client,node_medlineplus,node_compose_deployment toneNeutral
```

## Components

### React Dashboard

Browser-facing upload, review, history, and chat experience.

- [Dashboard entry](https://github.com/inkithai/ygc/blob/main/medreport_dashboard/src/main.jsx): React/Vite app · `medreport_dashboard/src/main.jsx`
- [Routes & auth](https://github.com/inkithai/ygc/blob/main/medreport_dashboard/src/Routes.jsx): access boundary · Protected routes and authentication state gate dashboard workflows. · `medreport_dashboard/src/Routes.jsx`
- [Upload & review](https://github.com/inkithai/ygc/blob/main/medreport_dashboard/src/pages/upload-report/index.jsx): report workflow · `medreport_dashboard/src/pages/upload-report/index.jsx`
- [Evidence viewer](https://github.com/inkithai/ygc/blob/main/medreport_dashboard/src/components/evidence/SourcePageViewer.jsx): provenance UI · Renders source pages and extraction locations. · `medreport_dashboard/src/components/evidence/SourcePageViewer.jsx`

### Application API

Node.js HTTP and identity boundary.

- [Node application API](https://github.com/inkithai/ygc/blob/main/Backend/index.js): Node.js HTTP API · Primary application-facing API and request orchestrator. · `Backend/index.js`
- [Auth middleware](https://github.com/inkithai/ygc/blob/main/Backend/middleware/auth.js): security boundary · `Backend/middleware/auth.js`
- [User, chat & report routes](https://github.com/inkithai/ygc/blob/main/Backend/routes/chatRoutes.js): route modules · `Backend/routes/chatRoutes.js`
- [Report model](https://github.com/inkithai/ygc/blob/main/Backend/models/reportModel.js): MongoDB model · `Backend/models/reportModel.js`

### Clinical Processing Service

Python extraction, reasoning, and report-scoped conversation.

- [Clinical service API](https://github.com/inkithai/ygc/blob/main/rag_model/rag_api.py): Python RAG API · Receives document-processing and clinical query requests. · `rag_model/rag_api.py`
- [Document extraction](https://github.com/inkithai/ygc/blob/main/rag_model/extraction/parser.py): ingestion pipeline · Preprocessing, OCR, quality checks, parsing, and vision/text fallbacks retain source provenance. · `rag_model/extraction/parser.py`
- [Clinical fact extraction](https://github.com/inkithai/ygc/blob/main/rag_model/clinical_extraction.py): structured extraction · `rag_model/clinical_extraction.py`
- [Clinical pipeline](https://github.com/inkithai/ygc/blob/main/rag_model/core/pipeline.py): reasoning orchestration · Resolves patient context and applies clinical derivations. · `rag_model/core/pipeline.py`
- [Patient graph](https://github.com/inkithai/ygc/blob/main/rag_model/core/patient_graph.py): clinical context graph · `rag_model/core/patient_graph.py`
- [Clinical review & risk](https://github.com/inkithai/ygc/blob/main/rag_model/core/clinical_review.py): rules and risk review · `rag_model/core/clinical_review.py`
- [Safety & response validation](https://github.com/inkithai/ygc/blob/main/rag_model/response_validator.py): answer safety boundary · Constrains answers, confidence, citations, abstention, and fallbacks. · `rag_model/response_validator.py`
- [Chat context & intent](https://github.com/inkithai/ygc/blob/main/rag_model/chat/context_builder.py): conversation orchestration · Builds report context, detects intent, and maintains follow-up state. · `rag_model/chat/context_builder.py`
- [PDF output generator](https://github.com/inkithai/ygc/blob/main/rag_model/pdf_generator.py): report output · `rag_model/pdf_generator.py`
- [Clinical datasets](https://github.com/inkithai/ygc/blob/main/rag_model/data/drug_interactions.json): medical reference data · Provides interactions, dose limits, mappings, trends, and specialist rules. · `rag_model/data/drug_interactions.json`

### Other components

- [MongoDB](https://github.com/inkithai/ygc/blob/main/Backend/db/index.js): persistence · Stores application records and Python clinical/history data. · `Backend/db/index.js`
- [LLM client](https://github.com/inkithai/ygc/blob/main/rag_model/core/groq_client.py): external AI service · External generation dependency with degradation-safe handling. · `rag_model/core/groq_client.py`
- [MedlinePlus client](https://github.com/inkithai/ygc/blob/main/rag_model/medlineplus_client.py): external knowledge service · `rag_model/medlineplus_client.py`
- [Compose deployment](https://github.com/inkithai/ygc/blob/main/docker-compose.yml): multi-service deployment · Runs the platform services; Oracle deployment extends this composition. · `docker-compose.yml`

## Connections

- Dashboard entry → Routes & auth: initializes
- Routes & auth → Upload & review: authorizes
- Upload & review → Node application API: uploads and queries
- Upload & review → Evidence viewer: reviews evidence
- Node application API → Auth middleware: protects requests
- Auth middleware → User, chat & report routes: permits authenticated requests
- User, chat & report routes → Report model: persists report records
- Report model → MongoDB: stores
- User, chat & report routes → Clinical service API: orchestrates clinical work
- Clinical service API → Document extraction: ingests documents
- Document extraction → Clinical fact extraction: produces provenance-linked text
- Clinical fact extraction → Clinical pipeline: supplies structured facts
- Clinical pipeline → Patient graph: builds patient context
- Patient graph → Clinical review & risk: supports review
- Clinical datasets → Clinical review & risk: supplies medical rules and references
- Clinical review & risk → Safety & response validation: produces assessed findings
- Clinical service API → Chat context & intent: handles report questions
- Chat context & intent → Clinical pipeline: provides intent and context
- Safety & response validation → LLM client: uses constrained generation
- Safety & response validation → MedlinePlus client: uses external knowledge
- Safety & response validation → PDF output generator: generates validated output
- Clinical service API → MongoDB: stores clinical history
- Document extraction → Evidence viewer: returns source locations
- Compose deployment → Node application API: deploys
- Compose deployment → Clinical service API: deploys
- Compose deployment → MongoDB: deploys