# manuelhettich/medicat architecture

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

- Interactive diagram: https://gitdiagram.com/manuelhettich/medicat
- Repository: https://github.com/manuelhettich/medicat

## Overview

- A Python-based backend that performs the analysis pipeline, including PDF processing, text extraction, refinement via Large Language Model (LLM) calls, categorization, and CSV generation.
- An iOS client project (MediCat) written in Swift, which likely serves as one of the frontends for interacting with or displaying processed clinical guideline information.

##### Main components
- Frontend Components:
- iOS Client: Shown by the “iOS” directory containing Swift files (ContentView.swift, FeedView.swift, etc.). This application provides the user interface on mobile and probably consumes backend services.
- (Optional) Web Frontend: Indicated by presence of “templates” and “static” directories and the upload HTML page. This shows that a web-based UI could be available.
- Backend Components:
- Core Application Server: Represented by files like app.py, which likely initializes and runs the web server. Use of gunicorn_config.py hints at deployment with Gunicorn.
- Processing Modules: This includes plaintext2.py for PDF-to-text extraction, chatgpt_calls.py for interacting with the LLM endpoints, generateCSV.py, and stats.py for post-processing reports.
- File Storage: The “uploads” directory holds intermediate and final outputs (e.g., plain_text, paragraphs.txt, evaluated paragraphs) which the system uses as data storage for processing results.
- External Services:
- Custom LLM Endpoints: The README details multiple LLM endpoints used for refining text and categorizing content; these should be shown as external service components.
- OpenAI API: Since an API key is mandatory (OPENAI_API_KEY), indicate the dependency on OpenAI’s API.
- DigitalOcean Deployment: The “.do/deploy.template.yaml” and DigitalOcean deployment button from the README suggest cloud hosting, which can be shown as the deployment environment.

##### Relationships and Interactions
- The frontend sends a request to the backend server (app.py) through well-defined endpoints (like /process_pdf).
- The backend receives a PDF file upload, and plaintext2.py is used to extract raw text, storing results in the “uploads” directory.
- The extracted text is passed to a refinement module (likely via chatgpt_calls.py) which in turn calls an external LLM endpoint to format and clean the text.
- The refined output is then further processed by categorization and ranking via additional LLM calls, producing outputs like “paragraphs.txt” and “paragraphs_evaluated.txt”, culminating in a CSV file.
- The final results are then returned to the frontend for visualization.

##### Architectural Patterns and Technologies
- Mention that the system uses a pipeline design, breaking the processing into distinct stages with clear responsibility:
- Extraction → Refinement → Categorization.
- Separation of concerns between the Python backend handling data processing and the iOS/web frontend for user interaction.
- Integration of external services (custom LLM endpoints, OpenAI API) as an essential part of the data processing pipeline.
- Mention the use of a WSGI server (Gunicorn) for deploying the backend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Styles
    classDef frontend fill:#DDEBF7,stroke:#6BAED6,stroke-width:2px;
    classDef backend fill:#FCE5CD,stroke:#F4A460,stroke-width:2px;
    classDef external fill:#E2EFDA,stroke:#78C679,stroke-width:2px;
    classDef storage fill:#FFF2CC,stroke:#FFCC00,stroke-width:2px;
    
    %% User Interfaces
    subgraph "User Interfaces"
        UI1["iOS Client (MediCat)"]:::frontend
        UI2["Web Frontend (upload.html)"]:::frontend
    end

    %% Backend Processing
    subgraph "Backend Processing"
        BS1["Core Application Server (app.py)"]:::backend
        BS2["Gunicorn Deployment (gunicorn_config.py)"]:::backend
        BS3["PDF Extraction Module (plaintext2.py)"]:::backend
        BS4["LLM Integration Module (chatgpt_calls.py)"]:::backend
        BS5["CSV Generation (generateCSV.py)"]:::backend
        BS6["Reporting & Stats (stats.py)"]:::backend
    end

    %% File Storage
    FS["File Storage (uploads)"]:::storage

    %% External Services
    subgraph "External Services"
        EX1["Custom LLM Endpoints"]:::external
        EX2["OpenAI API"]:::external
        EX3["DigitalOcean Deployment (.do/deploy.template.yaml)"]:::external
    end

    %% Data Flow / Interactions
    UI1 -->|"submitsPDF"| BS1
    UI2 -->|"submitsPDF"| BS1

    BS1 -->|"callsExtraction"| BS3
    BS3 -->|"savesExtractedText"| FS

    BS1 -->|"triggersLLM"| BS4
    BS4 -->|"refinesText"| EX1
    BS4 -->|"usesAPIKey"| EX2

    BS1 -->|"initiatesCSV"| BS5
    BS5 -->|"createsCSVReport"| FS

    BS1 -->|"generatesReports"| BS6
    BS6 -->|"savesStats"| FS

    EX3 ---|"hostsBackend"| BS1
    BS2 ---|"supportsDeployment"| BS1

    %% Click Events
    click UI1 "https://github.com/manuelhettich/medicat/tree/main/iOS/MediCat"
    click UI2 "https://github.com/manuelhettich/medicat/tree/main/templates"
    click BS1 "https://github.com/manuelhettich/medicat/blob/main/app.py"
    click BS2 "https://github.com/manuelhettich/medicat/blob/main/gunicorn_config.py"
    click BS3 "https://github.com/manuelhettich/medicat/blob/main/plaintext2.py"
    click BS4 "https://github.com/manuelhettich/medicat/blob/main/chatgpt_calls.py"
    click BS5 "https://github.com/manuelhettich/medicat/blob/main/generateCSV.py"
    click BS6 "https://github.com/manuelhettich/medicat/blob/main/stats.py"
    click FS "https://github.com/manuelhettich/medicat/tree/main/uploads"
    click EX3 "https://github.com/manuelhettich/medicat/blob/main/.do/deploy.template.yaml"
```
