# niyasahamedk/medical-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/niyasahamedk/medical-chatbot
- Repository: https://github.com/niyasahamedk/medical-chatbot

## Overview

##### Project type & purpose (from file tree + README)
This is a small Python application/package for a **Medical Chatbot**. The structure suggests:
- A **runtime application entrypoint**: `app.py` (likely launches a web UI or API server).
- A **reusable Python package** under `src/` containing the chatbot’s core logic:
- `src/prompt.py` (prompt construction / prompt templates for medical domain behavior)
- `src/helper.py` (shared utilities: formatting, request wrappers, preprocessing/postprocessing, etc.)
- A **templating layer**: `template.py` (could be UI template, prompt template scaffolding, or response formatting template).
- **Packaging & dependency management**: `setup.py`, `requirements.txt`.
- **R&D / experimentation**: `research/trials.ipynb`.

Because the repository is small, being “very detailed” means: **split modules and flows explicitly**, and clearly label external calls (LLM/provider, any databases if present).

##### Runtime / execution components
- **User** (doctor/patient/tester)
- **Chat UI / Client** (whatever `app.py` exposes)
- If `app.py` uses Streamlit/Gradio: it’s a **Web UI**
- If `app.py` uses Flask/FastAPI: it’s an **HTTP API**
- If it’s CLI: it’s a **terminal app**

- **Application Orchestrator (`app.py`)**
- Routes user messages to the chatbot core
- Handles session state (if any)
- Handles request/response formatting

##### Core “business logic” components (in `src/`)
- **Prompt Builder (`src/prompt.py`)**
- Defines system prompt, medical constraints, safety notes, formatting rules
- May contain prompt templates, few-shot examples, roles/messages construction

- **Helpers / Utilities (`src/helper.py`)**
- Likely includes: text cleaning, logging, config loading, API wrappers, parsing model output, guardrails, etc.

- **Package init (`src/__init__.py`)**
- Exposes top-level functions/classes

##### Templates
- **`template.py`**
- It as a component responsible for:
- response formatting / UI formatting, OR
- prompt skeleton templating
> Again, confirm by reading its functions/classes.

Even though not visible in the tree, a medical chatbot almost certainly relies on one of:
- **LLM Provider API** (OpenAI / Anthropic / local model server)
- Optional (only include if present in code): **Vector DB / Retrieval** (FAISS/Pinecone/Chroma), **Medical knowledge source**, **Database for conversations**, **Telemetry/Logging**
- `requirements.txt` (e.g., `openai`, `langchain`, `chromadb`, `pinecone`, `faiss`, `fastapi`, `streamlit`, etc.)
- `app.py` imports and runtime code

##### `app.py` → Prompt Builder (`src/prompt.py`)
- “Build system + user message prompt”
##### `app.py` → Helpers (`src/helper.py`)
- “Preprocess input / validate / postprocess output”
##### `app.py` (or helper) → External LLM API
- “Send prompt/messages, receive completion”
##### If `template.py` formats output
- `app.py` → `template.py` → UI
##### If configs are used (env vars, keys)
- A small **Config/Secrets** node (e.g., environment variables) feeding `app.py`/helpers.

- “user message”
- “prompt/messages”
- “completion/response”
- “formatted response”
- “API key/config”

##### Architectural patterns to highlight (based on structure)
From the tree, the pattern is likely:
- **Thin orchestrator (`app.py`) + modularized core** in `src/`
- **Prompt-as-code** (prompt logic isolated in `src/prompt.py`)
- **Utility layer** (helpers provide shared cross-cutting behaviors)

- “Application Layer” (app.py)
- “Domain/Chatbot Logic” (prompt.py)
- “Shared Utilities” (helper.py)
- “External Dependency” (LLM API)

##### What

Include:
- User
- Browser/Client (or API client)
- Python App (`app.py`)
- External LLM API
- (Optional) Config/Secrets

Inside “Python App” boundary, include:
- Request handling / session management (in `app.py`)
- Prompt construction (`src/prompt.py`)
- Pre/post processing utilities (`src/helper.py`)
- Templating/formatting (`template.py`)
- LLM call wrapper (could be inside helper.py; label it explicitly if so)

##### Open `requirements.txt` and list frameworks
- streamlit/gradio/flask/fastapi?
- openai/langchain?
##### Open `app.py`
- entrypoint type (UI vs API vs CLI)
- where LLM call occurs (directly in app.py or via helper)
##### Open `src/prompt.py`
- prompt format (chat messages vs plain text)
##### Open `src/helper.py` and `template.py`

Only after those checks should you finalize labels like “Streamlit UI” vs “FastAPI Server”, “OpenAI API” vs “Local Ollama Server”, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% External Actors / Clients
    %% =========================
    U["User (doctor/patient/tester)"]:::actor
    C["Chat Client (Web UI / API Client / CLI)"]:::client

    %% =========================
    %% Codebase Boundary (Repo)
    %% =========================
    subgraph "Codebase Boundary (This Repo)"
        direction TB

        subgraph "Runtime Application Layer"
            direction TB
            APP["Application Orchestrator (app.py)"]:::app
            TPL["Templating / Formatting (template.py)"]:::template
        end

        subgraph "Core Chatbot Package (src/)"
            direction TB
            INIT["Package Init / Public Exports (src/__init__.py)"]:::pkg
            PROMPT["Prompt Builder (src/prompt.py)"]:::module
            HELP["Helpers / Utilities (src/helper.py)"]:::module

            subgraph "Helper Responsibilities (conceptual)"
                direction TB
                PRE["Preprocess / Validate Input"]:::sub
                LLMW["LLM Call Wrapper / Request Builder"]:::sub
                POST["Postprocess / Guardrails / Parsing"]:::sub
            end
        end

        subgraph "Build & Dependency Metadata"
            direction TB
            REQ["Runtime Dependencies (requirements.txt)"]:::meta
            SETUP["Packaging / Install Config (setup.py)"]:::meta
        end

        subgraph "Research / Experimentation (Non-Prod)"
            direction TB
            NB["Notebook Trials (research/trials.ipynb)"]:::research
        end
    end

    %% =========================
    %% External Services Boundary
    %% =========================
    subgraph "External Services"
        direction TB
        LLM["LLM Provider API (OpenAI/Anthropic/Local Server)"]:::external
        CFG["Config / Secrets (Env vars, API keys)"]:::external2
    end

    %% =========================
    %% Main Runtime Flow
    %% =========================
    U -->|"user_message"| C
    C -->|"request"| APP

    APP -->|"build_prompt(messages)"| PROMPT
    APP -->|"pre_or_post_processing"| HELP
    APP -->|"format_response"| TPL

    HELP -->|"preprocess_input"| PRE
    HELP -->|"wrap_llm_request"| LLMW
    HELP -->|"postprocess_output"| POST

    CFG -->|"api_key/config"| APP
    CFG -->|"api_key/config"| HELP

    APP -->|"prompt/messages"| LLM
    LLM -->|"completion/response"| APP

    APP -->|"formatted_response"| C
    C -->|"answer"| U

    %% =========================
    %% Non-Prod / Feedback Loop
    %% =========================
    NB -->|"iterate_prompts/helpers"| PROMPT
    NB -->|"experiment_utils"| HELP

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click APP "https://github.com/niyasahamedk/medical-chatbot/blob/main/app.py"
    click TPL "https://github.com/niyasahamedk/medical-chatbot/blob/main/template.py"
    click INIT "https://github.com/niyasahamedk/medical-chatbot/blob/main/src/__init__.py"
    click PROMPT "https://github.com/niyasahamedk/medical-chatbot/blob/main/src/prompt.py"
    click HELP "https://github.com/niyasahamedk/medical-chatbot/blob/main/src/helper.py"
    click REQ "https://github.com/niyasahamedk/medical-chatbot/blob/main/requirements.txt"
    click SETUP "https://github.com/niyasahamedk/medical-chatbot/blob/main/setup.py"
    click NB "https://github.com/niyasahamedk/medical-chatbot/blob/main/research/trials.ipynb"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#1f2937,stroke:#0b1220,color:#ffffff,stroke-width:1px
    classDef client fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1px
    classDef app fill:#22c55e,stroke:#15803d,color:#052e16,stroke-width:1px
    classDef template fill:#34d399,stroke:#047857,color:#052e16,stroke-width:1px
    classDef pkg fill:#a78bfa,stroke:#6d28d9,color:#1f1147,stroke-width:1px
    classDef module fill:#c4b5fd,stroke:#7c3aed,color:#1f1147,stroke-width:1px
    classDef sub fill:#ede9fe,stroke:#8b5cf6,color:#1f1147,stroke-width:1px
    classDef external fill:#fb7185,stroke:#9f1239,color:#4a0716,stroke-width:1px
    classDef external2 fill:#fda4af,stroke:#9f1239,color:#4a0716,stroke-width:1px
    classDef research fill:#fbbf24,stroke:#b45309,color:#451a03,stroke-width:1px
    classDef meta fill:#94a3b8,stroke:#334155,color:#0f172a,stroke-width:1px
```
