# tech5s5/doctorsurveypredictor architecture

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

- Interactive diagram: https://gitdiagram.com/tech5s5/doctorsurveypredictor
- Repository: https://github.com/tech5s5/doctorsurveypredictor

## Overview

##### Project Type and Purpose
- The project is a full-stack web application designed to predict which doctors (NPIs) might participate in a survey at a given time.
- It integrates an interactive HTML/JavaScript frontend with a FastAPI backend.
- The backend handles model inference using pre-trained ML artifacts stored in the models directory, with results downloadable as CSV files.

##### Main Components
a. Client/Frontend:
- Represented by the HTML page in the templates folder (index.html).
- Provides an interface with a time slot dropdown (AM/PM, with specified minute intervals) and a “Predict” button for invoking predictions.
b. FastAPI Backend:
- The main application is located in main.py.
- It exposes endpoints that serve the UI, process the prediction request, interact with the ML model, and return the prediction results (CSV file).
c. Machine Learning Model Component:
- Stored in the models directory. This includes:
- npi_model.pkl – the main predictive model.
- label_encoders.pkl – supporting pre-processing data.
- dummy_npi_data.xlsx – potentially used to feed or test the model.
d. Data Handling & Output:
- Results or model predictions are formatted into CSV files for download.
- Dependencies are managed via requirements.txt to ensure the correct libraries are used (e.g., FastAPI, Uvicorn, TensorFlow, Pandas).

##### Relationships and Interactions
- The user interacts with the Frontend by selecting a time slot.
- The browser sends an HTTP request (likely via AJAX/fetch) to the FastAPI backend.
- The FastAPI application (main.py) loads the ML model and any required encoders from the models directory.
- The prediction is formatted into a downloadable CSV file which is returned to the frontend.
- The UI then provides the option to download or view the prediction output.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear delineation between the UI (frontend), business logic (FastAPI backend), and the ML model (in the models directory).
- MVC-Like Structure: The HTML page acts as the View, FastAPI handles Controller-like responsibilities, and the ML model/data are the Models.
- Dependency Management: Use of a requirements file ensures that all dependencies are predictable and maintainable.
- Scalability: The inclusion of FastAPI and the use of asynchronous Uvicorn suggests considerations for scalability and performance.

##### Elements
- "Client/Browser" (Frontend, displaying index.html).
- "FastAPI Application" (main.py), highlighting endpoints that serve the UI and process prediction requests.
- "ML Model & Data Artifacts" (inside the models directory – include npi_model.pkl, label_encoders.pkl, and dummy_npi_data.xlsx).
- From "Client/Browser" → to "FastAPI Application" (representing HTTP requests).
- From "FastAPI Application" → to "ML Model & Data Artifacts" (representing model loading and prediction logic).
- From "FastAPI Application" back to "Client/Browser" (representing the CSV file output).

- Frontend (HTML UI) communicating with the FastAPI backend.
- Backend (main.py) acting as the orchestrator, calling into the ML model stored in the models directory.
- The flow of data from the user input to the prediction output (CSV download).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Component
    F["Client/Browser (HTML UI)"]:::frontend

    %% Backend Component
    B["FastAPI Application"]:::backend

    %% Dependency Management Component
    D["Dependency Management (requirements.txt)"]:::dep

    %% ML Model & Data Artifacts Subgraph
    subgraph "ML Model & Data Artifacts"
        M1["npi_model.pkl"]:::model
        M2["label_encoders.pkl"]:::model
        M3["dummy_npi_data.xlsx"]:::model
    end

    %% Data Flow Connections
    F -->|"HTTP-Request"| B
    B -->|"Load-Model"| M1
    B -->|"Load-Model"| M2
    B -->|"Load-Model"| M3
    B -->|"Return-CSV"| F
    D -->|"Dependencies"| B

    %% Click Events
    click F "https://github.com/tech5s5/doctorsurveypredictor/blob/main/templates/index.html"
    click B "https://github.com/tech5s5/doctorsurveypredictor/blob/main/main.py"
    click M1 "https://github.com/tech5s5/doctorsurveypredictor/blob/main/models/npi_model.pkl"
    click M2 "https://github.com/tech5s5/doctorsurveypredictor/blob/main/models/label_encoders.pkl"
    click M3 "https://github.com/tech5s5/doctorsurveypredictor/blob/main/models/dummy_npi_data.xlsx"
    click D "https://github.com/tech5s5/doctorsurveypredictor/blob/main/requirements.txt"

    %% Style Definitions
    classDef frontend fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef backend fill:#aed6f1,stroke:#1f618d,stroke-width:2px;
    classDef model fill:#abebc6,stroke:#229954,stroke-width:2px;
    classDef dep fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
```
