# cos30018-2025-sem2-groupd1/medicaldiagnosissystem architecture

> Architecture diagram of the GitHub repository cos30018-2025-sem2-groupd1/medicaldiagnosissystem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem
- Repository: https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Medical AI Assistant”) with a FastAPI backend, a static/JavaScript frontend, AI-model integrations, and MongoDB persistence.
- Purpose: offer an AI-powered medical chatbot that keeps patient-centric memory, supports doctors/patients workflows, and persists data in MongoDB.

##### File‐Structure Analysis
- Top‐level: Docker/Docker-Compose files for containerization; `requirements*.txt`; setup guides.
- `src/api/routes/`: HTTP controllers (FastAPI endpoints) grouped by resource (chat, session, user/patient, system, static).
- `src/core/`: In‐memory caching and context-building (LRU short-term, session history).
- `src/data/`: Repository layer for MongoDB operations (connection, CRUD on sessions/messages/patients/users/medical KB).
- `src/services/`: Business logic for AI interactions (Gemini calls, NVIDIA summariser fallback, audio transcription).
- `src/models/`: Pydantic or ORM models for request/response schemas.
- `src/utils/`: Helpers (embeddings, logging, API-key rotator).
- `src/main.py` or `start.py`: FastAPI app entrypoint.
- `static/`: Frontend assets (HTML/CSS/JS).
- `tests/`: Unit/integration tests (e.g., Mongo tests).

##### README Insights
- High-level architecture: layered backend (memory, data, API).
- Key endpoints and flows described.
- Technology stack: Python 3.11, FastAPI, MongoDB, Docker, JS/CSS frontend, external AI APIs.

##### Main Components
a. Frontend (Browser)
- Static assets served by FastAPI (`/static`) or CDN.
- JavaScript app: UI modules (chat, sessions sidebar, patient/doctor modals).
b. Backend API (FastAPI App)
- HTTP Routes → Controllers (`src/api/routes`).
- Business core:
– Memory Manager (LRU cache + session history builder).
– Services: Gemini API, NVIDIA summariser, audio transcription.
- Data Layer: Repository modules interacting with MongoDB.
- Config & Utils: Settings loader, key rotator, logger.
c. Database
- MongoDB (persist sessions, messages, patient/doctor records, long-term memory).
d. External Services
- Gemini AI API
- NVIDIA summariser service
e. Infrastructure
- Docker container for backend + container for MongoDB (via Docker Compose)

##### Relationships and Data Flow
1. Browser → HTTP (JSON) → FastAPI routes
2. Route handler calls → Core/Memory to build context
3. Core invokes → Services (Gemini or fallback NVIDIA summariser)
4. Service returns → generated response
5. Handler persists → messages & memory summaries via Data/Repository → MongoDB
6. Response → back to Browser
7. Static file requests → served by FastAPI static route

##### Architectural Patterns & Principles
- Layered Architecture: Routes → Core/Services → Data → DB
- Repository Pattern for data access
- Cache + Persistence: short-term LRU + long-term Mongo
- Key Rotator for load-balancing external API keys
- Containerization for environment consistency

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        UI["Static Assets & UI"]:::frontend
    end

    %% Backend Container
    subgraph "Backend (Docker Container)"
        %% Controllers
        subgraph "API Controllers"
            Chat["Chat Endpoint"]:::controller
            SessionEP["Session Endpoint"]:::controller
            UserEP["User Endpoint"]:::controller
            PatientEP["Patient Endpoint"]:::controller
            DoctorEP["Doctor Endpoint"]:::controller
            SystemEP["System Endpoint"]:::controller
            AudioEP["Audio Endpoint"]:::controller
            StaticRoute["Static File Route"]:::controller
        end

        %% Core & Memory
        subgraph "Core & Memory"
            MemoryMgr["Memory Manager"]:::core
            ShortTerm["Short-term Memory (LRU)"]:::core
            History["Session History Builder"]:::core
            Prompt["Prompt Constructor"]:::core
            SessionState["Session Orchestration"]:::core
        end

        %% Services
        subgraph "Services"
            Gemini["Gemini AI Service"]:::external
            Nvidia["NVIDIA Summariser"]:::external
            Summary["Medical Response Orchestration"]:::services
            AudioTrans["Audio Transcription"]:::services
        end

        %% Data Layer
        subgraph "Data Repositories"
            MongoConn["MongoDB Connection"]:::data
            UserRepo["Account/User Repo"]:::data
            PatientRepo["Patient Records Repo"]:::data
            SessionRepo["Session Records Repo"]:::data
            MessageRepo["Message Records Repo"]:::data
            MedicalRepo["Medical Entries Repo"]:::data
        end

        Config["Config & Helpers"]:::helper
        App["App Entrypoint"]:::entry
    end

    %% Database
    subgraph "Database (MongoDB)"
        MongoDB["MongoDB"]:::db
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Docker["Docker Compose & Dockerfile"]:::infra
    end

    %% Connections
    UI -->|"HTTP/JSON"| Chat
    UI -->|"HTTP/JSON"| SessionEP
    UI -->|"HTTP/JSON"| UserEP
    UI -->|"HTTP/JSON"| PatientEP
    UI -->|"HTTP/JSON"| DoctorEP
    UI -->|"HTTP/JSON"| SystemEP
    UI -->|"HTTP/JSON"| AudioEP
    UI -->|"Request Static"| StaticRoute

    Chat -->|calls| MemoryMgr
    SessionEP -->|calls| MemoryMgr
    UserEP -->|calls| MemoryMgr
    PatientEP -->|calls| MemoryMgr
    DoctorEP -->|calls| MemoryMgr
    SystemEP -->|calls| MemoryMgr
    AudioEP -->|calls| MemoryMgr
    StaticRoute -->|serves| UI

    MemoryMgr --> ShortTerm
    MemoryMgr --> History
    MemoryMgr --> Prompt
    MemoryMgr --> SessionState

    MemoryMgr -->|REST API| Gemini
    MemoryMgr -->|on failure| Nvidia
    Gemini -->|response| MemoryMgr
    Nvidia -->|summary| MemoryMgr
    MemoryMgr -->|orchestration| Summary
    SessionEP -->|transcribe| AudioTrans

    Chat -->|persist| SessionRepo
    Chat -->|persist| MessageRepo
    SessionEP -->|persist| SessionRepo
    UserEP -->|persist| UserRepo
    PatientEP -->|persist| PatientRepo
    DoctorEP -->|persist| UserRepo
    Summary -->|persist| MedicalRepo

    SessionRepo -->|calls| MongoConn
    MessageRepo -->|calls| MongoConn
    UserRepo -->|calls| MongoConn
    PatientRepo -->|calls| MongoConn
    MedicalRepo -->|calls| MongoConn
    MongoConn -->|driver| MongoDB

    Config -->|settings| App
    App -->|launch| Chat
    App -->|launch| SessionEP

    Docker -->|hosts| Backend
    Docker -->|hosts| MongoDB

    %% Click Events
    click UI "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/tree/main/static/"
    click Chat "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/api/routes/chat.py"
    click SessionEP "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/api/routes/session.py"
    click UserEP "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/api/routes/user.py"
    click PatientEP "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/api/routes/patients.py"
    click DoctorEP "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/api/routes/doctors.py"
    click SystemEP "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/api/routes/system.py"
    click AudioEP "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/api/routes/audio.py"
    click StaticRoute "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/api/routes/static.py"
    click ShortTerm "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/core/memory.py"
    click History "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/core/history.py"
    click Prompt "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/core/prompt_builder.py"
    click SessionState "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/core/session.py"
    click MongoConn "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/data/connection.py"
    click UserRepo "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/data/repositories/account.py"
    click PatientRepo "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/data/repositories/patient.py"
    click SessionRepo "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/data/repositories/session.py"
    click MessageRepo "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/data/repositories/message.py"
    click MedicalRepo "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/data/repositories/medical.py"
    click Gemini "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/services/gemini.py"
    click Nvidia "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/services/nvidia.py"
    click Summary "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/services/medical_response.py"
    click AudioTrans "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/services/audio_transcription.py"
    click App "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/src/main.py"
    click Docker "https://github.com/cos30018-2025-sem2-groupd1/medicaldiagnosissystem/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef controller fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef core fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef services fill:#FFFDE7,stroke:#F9A825,color:#F9A825
    classDef external fill:#FFE0B2,stroke:#EF6C00,color:#EF6C00
    classDef data fill:#EDE7F6,stroke:#5E35B1,color:#5E35B1
    classDef helper fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef entry fill:#E1F5FE,stroke:#0288D1,color:#0288D1
    classDef db fill:#CFD8DC,stroke:#455A64,color:#455A64
    classDef infra fill:#ECEFF1,stroke:#263238,color:#263238
```
