# shiwangeegg/maya-ai-based-pcos-detection-system architecture

> Architecture diagram of the GitHub repository shiwangeegg/maya-ai-based-pcos-detection-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shiwangeegg/maya-ai-based-pcos-detection-system
- Repository: https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system

## Overview

PCOS Detect is a clinical decision-support application: users enter clinical data and optionally upload an ultrasound or medical PDF, then receive a multimodal PCOS risk assessment and explainability/recommendation features. The frontend also supports accounts, profiles, and saved assessment history. The main inference and parsing flows are visible in sampled backend excerpts and README documentation; several frontend and API implementation files were not sampled, so their detailed internal calls are not represented.

Main entry points: [`app/api/pcos.py`](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/api/pcos.py) (PCOS endpoints), [`app/main.py`](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/main.py) (FastAPI application), [`frontend/app/results/page.tsx`](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/results/page.tsx) (Results dashboard), [`app/auth/auth_router.py`](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/auth/auth_router.py) (Auth service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Patient experience"]
  node_web["Next.js app<br/>[layout.tsx]"]
  node_assessment_ui["Assessment workflow<br/>[page.tsx]"]
  node_results_ui["Results dashboard<br/>[page.tsx]"]
  node_history_ui["Assessment history<br/>[page.tsx]"]
  node_profile_ui["Profile pages<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_application["FastAPI application<br/>[main.py]"]
  node_pcos_api["PCOS endpoints<br/>[pcos.py]"]
  node_auth_api["Authentication endpoints<br/>[auth.py]"]
  node_assessment_api["Assessment endpoints<br/>[assessments.py]"]
  node_profile_api["Profile endpoints<br/>[profile.py]"]
end

subgraph group_clinical["Assessment services"]
  node_parser["PDF parser<br/>[document_parser.py]"]
  node_field_registry["Clinical field registry<br/>[field_registry.py]"]
  node_inference["Multimodal inference"]
  node_gradcam["Grad-CAM explanation<br/>[gradcam_service.py]"]
  node_recommendations["Recommendations"]
end

subgraph group_identity["Identity and records"]
  node_auth_router["Auth service<br/>[auth_router.py]"]
  node_jwt["JWT utilities<br/>[jwt_utils.py]"]
  node_profile_service["Profile service<br/>[profile_service.py]"]
  node_assessment_service["Assessment service"]
end

subgraph group_persistence["Database models"]
  node_db[("SQLite database<br/>[database.py]")]
  node_user_model[("User model<br/>[user_models.py]")]
  node_profile_model[("Profile model<br/>[profile_models.py]")]
  node_assessment_model[("Assessment model")]
end

node_patient(("Patient"))

node_patient -->|"uses"| node_web
node_web -->|"opens"| node_assessment_ui
node_assessment_ui -.->|"submits assessment"| node_api_client
node_api_client -.->|"sends request"| node_pcos_api
node_pcos_api -->|"runs inference"| node_inference
node_pcos_api -->|"parses report"| node_parser
node_parser -->|"uses field definitions"| node_field_registry
node_pcos_api -->|"requests explanation"| node_gradcam
node_pcos_api -->|"requests recommendations"| node_recommendations
node_pcos_api -->|"saves assessment"| node_assessment_service
node_pcos_api -.->|"returns assessment data"| node_assessment_api
node_pcos_api -.->|"returns risk results"| node_results_ui
node_results_ui -->|"displays results"| node_patient
node_results_ui -.->|"shows heatmap"| node_gradcam
node_application -->|"routes to"| node_pcos_api
node_application -->|"routes to"| node_auth_api
node_application -->|"routes to"| node_assessment_api
node_application -->|"routes to"| node_profile_api
node_auth_api -.->|"handles authentication"| node_auth_router
node_auth_router -->|"creates tokens"| node_jwt
node_auth_router -->|"queries users"| node_user_model
node_profile_api -->|"delegates profile work"| node_profile_service
node_profile_service -->|"reads and writes"| node_profile_model
node_assessment_service -->|"creates records"| node_assessment_model
node_assessment_api -->|"serves history"| node_assessment_model
node_user_model -->|"maps to"| node_db
node_profile_model -->|"maps to"| node_db
node_assessment_model -->|"maps to"| node_db
node_patient -.->|"registers or signs in"| node_auth_api
node_patient -.->|"manages profile"| node_profile_ui
node_patient -.->|"reviews history"| node_history_ui

click node_web "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/layout.tsx"
click node_assessment_ui "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/assess/page.tsx"
click node_results_ui "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/results/page.tsx"
click node_history_ui "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/history/page.tsx"
click node_profile_ui "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/profile/page.tsx"
click node_api_client "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/lib/api.ts"
click node_application "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/main.py"
click node_pcos_api "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/api/pcos.py"
click node_auth_api "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/api/auth.py"
click node_assessment_api "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/api/assessments.py"
click node_profile_api "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/api/profile.py"
click node_parser "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/parsing/document_parser.py"
click node_field_registry "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/parsing/field_registry.py"
click node_inference "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/services/multimodal_service.py"
click node_gradcam "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/services/gradcam_service.py"
click node_recommendations "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/services/recommendation_service.py"
click node_auth_router "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/auth/auth_router.py"
click node_jwt "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/auth/jwt_utils.py"
click node_profile_service "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/users/profile_service.py"
click node_assessment_service "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/assessments/assessment_service.py"
click node_db "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/database.py"
click node_user_model "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/users/user_models.py"
click node_profile_model "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/users/profile_models.py"
click node_assessment_model "https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/assessments/assessment_model.py"

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_web,node_assessment_ui,node_results_ui,node_history_ui,node_profile_ui,node_api_client toneBlue
class node_application,node_pcos_api,node_auth_api,node_assessment_api,node_profile_api toneAmber
class node_parser,node_field_registry,node_inference,node_gradcam,node_recommendations toneMint
class node_auth_router,node_jwt,node_profile_service,node_assessment_service toneRose
class node_db,node_user_model,node_profile_model,node_assessment_model,node_patient toneIndigo
```

## Components

### Patient experience

- [Next.js app](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/layout.tsx): `frontend/app/layout.tsx`
- [Assessment workflow](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/assess/page.tsx): `frontend/app/assess/page.tsx`
- [Results dashboard](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/results/page.tsx): `frontend/app/results/page.tsx`
- [Assessment history](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/history/page.tsx): `frontend/app/history/page.tsx`
- [Profile pages](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/app/profile/page.tsx): `frontend/app/profile/page.tsx`
- [API client](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Backend API

- [FastAPI application](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/main.py): `app/main.py`
- [PCOS endpoints](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/api/pcos.py): `app/api/pcos.py`
- [Authentication endpoints](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/api/auth.py): `app/api/auth.py`
- [Assessment endpoints](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/api/assessments.py): `app/api/assessments.py`
- [Profile endpoints](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/api/profile.py): `app/api/profile.py`

### Assessment services

- [PDF parser](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/parsing/document_parser.py): `app/parsing/document_parser.py`
- [Clinical field registry](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/parsing/field_registry.py): `app/parsing/field_registry.py`
- [Multimodal inference](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/services/multimodal_service.py): `app/services/multimodal_service.py`
- [Grad-CAM explanation](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/services/gradcam_service.py): `app/services/gradcam_service.py`
- [Recommendations](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/services/recommendation_service.py): `app/services/recommendation_service.py`

### Identity and records

- [Auth service](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/auth/auth_router.py): `app/auth/auth_router.py`
- [JWT utilities](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/auth/jwt_utils.py): `app/auth/jwt_utils.py`
- [Profile service](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/users/profile_service.py): `app/users/profile_service.py`
- [Assessment service](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/assessments/assessment_service.py): `app/assessments/assessment_service.py`

### Database models

- [SQLite database](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/database.py): `app/database.py`
- [User model](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/users/user_models.py): `app/users/user_models.py`
- [Profile model](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/users/profile_models.py): `app/users/profile_models.py`
- [Assessment model](https://github.com/shiwangeegg/maya-ai-based-pcos-detection-system/blob/main/app/assessments/assessment_model.py): `app/assessments/assessment_model.py`

### Other components

- **Patient**

## Connections

- Patient → Next.js app: uses
- Next.js app → Assessment workflow: opens
- Assessment workflow → API client: submits assessment
- API client → PCOS endpoints: sends request
- PCOS endpoints → Multimodal inference: runs inference (evidence: `app/api/pcos.py`)
- PCOS endpoints → PDF parser: parses report (evidence: `app/api/pcos.py`)
- PDF parser → Clinical field registry: uses field definitions (evidence: `app/parsing/document_parser.py`)
- PCOS endpoints → Grad-CAM explanation: requests explanation (evidence: `app/api/pcos.py`)
- PCOS endpoints → Recommendations: requests recommendations (evidence: `app/api/pcos.py`)
- PCOS endpoints → Assessment service: saves assessment (evidence: `app/api/pcos.py`)
- PCOS endpoints → Assessment endpoints: returns assessment data
- PCOS endpoints → Results dashboard: returns risk results
- Results dashboard → Patient: displays results
- Results dashboard → Grad-CAM explanation: shows heatmap
- FastAPI application → PCOS endpoints: routes to (evidence: `app/main.py`)
- FastAPI application → Authentication endpoints: routes to (evidence: `app/main.py`)
- FastAPI application → Assessment endpoints: routes to (evidence: `app/main.py`)
- FastAPI application → Profile endpoints: routes to (evidence: `app/main.py`)
- Authentication endpoints → Auth service: handles authentication
- Auth service → JWT utilities: creates tokens (evidence: `app/auth/auth_router.py`)
- Auth service → User model: queries users (evidence: `app/auth/auth_router.py`)
- Profile endpoints → Profile service: delegates profile work (evidence: `app/api/profile.py`)
- Profile service → Profile model: reads and writes (evidence: `app/users/profile_service.py`)
- Assessment service → Assessment model: creates records (evidence: `app/assessments/assessment_service.py`)
- Assessment endpoints → Assessment model: serves history (evidence: `app/api/assessments.py`)
- User model → SQLite database: maps to (evidence: `app/users/user_models.py`)
- Profile model → SQLite database: maps to (evidence: `app/users/profile_models.py`)
- Assessment model → SQLite database: maps to (evidence: `app/assessments/assessment_model.py`)
- Patient → Authentication endpoints: registers or signs in
- Patient → Profile pages: manages profile
- Patient → Assessment history: reviews history
