# melroyanthony/provet architecture

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

- Interactive diagram: https://gitdiagram.com/melroyanthony/provet
- Repository: https://github.com/melroyanthony/provet

## Overview

##### Project Type and Purpose
- Type: A Python-based “full-stack” tool that runs as a CLI or as a REST API microservice.
- Purpose: Ingest veterinary consultation JSON, call OpenAI LLM, render Jinja2 templates, and emit formatted discharge notes.

##### Main Architectural Components
A. Client Tier
– CLI interface: `provet_cli.py` and `provet/__main__.py`
– API interface: FastAPI app defined in `api/main.py`, served by Uvicorn (via Docker Compose)
B. Core Application Tier (`provet/core/`)
– App Facade (`app.py`): orchestrates the workflow
– Data Models (`data_models.py`): domain entities (consultation, note)
– IO Manager (`io_manager.py`): file I/O (load JSON, write output)
– LLM Service (`llm_service.py`): OpenAI API calls
C. Utility Tier (`provet/utils/`)
– Config loader (`config.py`): reads `.env` or env vars
– Template engine (`template_engine.py`): wraps Jinja2, applies templates in `provet/templates/`
D. External Services & Data
– OpenAI API (external “LLM” cloud service)
– Local JSON files (input in `data/`, output in `solution/`)
E. Deployment & Orchestration
– Dockerfile (multi-stage build + test stage)
– docker-compose.yml (brings up the API service)
– Shell scripts (`scripts/`) for setup/dev/cleanup

##### Relationships & Data Flows
1. User invokes CLI or sends HTTP request to API.
2. CLI/HTTP handler calls Core.App facade.
3. Core.App asks IO Manager to read consultation JSON → yields Data Models.
4. Core.App passes data models to LLM Service → makes HTTP call to OpenAI → receives generated text.
5. Core.App hands text + models to Template Engine → renders Jinja2 templates (`discharge_prompt.j2`, `system_message.j2`).
6. Core.App uses IO Manager to write formatted note JSON to disk (`solution/`).
7. API returns JSON response; CLI writes file and/or dumps to stdout.

##### Architectural Patterns & Design Principles
- Facade Pattern: `provet/core/app.py` central orchestration
- Separation of Concerns: I/O, data modeling, LLM interaction, templating, and config are each in their own module.
- Template-Based Rendering: Jinja2 templates exist under `provet/templates/`.
- Multi-Stage Docker Builds: enforce tests before production image.
- Modular Deployment: same core used by both CLI and API.

##### Technologies & Frameworks to Annotate
- Python 3.13+, uv (dependency manager)
- FastAPI + Uvicorn (API)
- Jinja2 (templating)
- OpenAI API (LLM backend)
- Docker + Docker Compose (containerization)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        CLI["CLI Interface"]:::interface
        API["API Interface"]:::interface
    end

    %% Core Application Tier
    subgraph "Core Application Tier"
        App["Core.App Facade"]:::core
        DM["Data Models"]:::core
        IO["IO Manager"]:::core
        LLM["LLM Service"]:::core
    end

    %% Utility Tier
    subgraph "Utility Tier"
        Config["Config Loader"]:::utils
        Template["Template Engine"]:::utils
        JinjaTemplates["Jinja2 Templates"]:::utils
    end

    %% Data Stores
    subgraph "Data Stores"
        Input["Consultation JSON"]:::data
        Output["Solution JSON"]:::data
    end

    %% External Services
    OpenAI["OpenAI API"]:::external

    %% Deployment & Orchestration
    subgraph "Deployment & Orchestration"
        Dockerfile["Dockerfile"]:::deploy
        Compose["docker-compose.yml"]:::deploy
        Scripts["Shell Scripts"]:::deploy
        Tests["Pytest Suite"]:::deploy
    end

    %% Connections
    CLI -->|"invoke"| App
    API -->|"HTTP request"| App
    App -->|"read JSON"| IO
    IO -->|"load models"| DM
    App -->|"invoke LLM"| LLM
    LLM -->|"call OpenAI"| OpenAI
    OpenAI -->|"response text"| LLM
    App -->|"render template"| Template
    Template -->|"uses templates"| JinjaTemplates
    App -->|"write output"| IO
    IO -->|"save JSON"| Output

    %% Deployment flows
    Dockerfile --> Compose
    Compose --> API

    %% Click Events
    click CLI "https://github.com/melroyanthony/provet/blob/main/provet_cli.py"
    click CLI "https://github.com/melroyanthony/provet/blob/main/provet/__main__.py"
    click API "https://github.com/melroyanthony/provet/blob/main/api/main.py"
    click App "https://github.com/melroyanthony/provet/blob/main/provet/core/app.py"
    click DM "https://github.com/melroyanthony/provet/blob/main/provet/core/data_models.py"
    click IO "https://github.com/melroyanthony/provet/blob/main/provet/core/io_manager.py"
    click LLM "https://github.com/melroyanthony/provet/blob/main/provet/core/llm_service.py"
    click Config "https://github.com/melroyanthony/provet/blob/main/provet/utils/config.py"
    click Config "https://github.com/melroyanthony/provet/blob/main/.env-template"
    click Template "https://github.com/melroyanthony/provet/blob/main/provet/utils/template_engine.py"
    click JinjaTemplates "https://github.com/melroyanthony/provet/blob/main/provet/templates/discharge_prompt.j2"
    click JinjaTemplates "https://github.com/melroyanthony/provet/blob/main/provet/templates/system_message.j2"
    click Input "https://github.com/melroyanthony/provet/blob/main/data/consultation1.json"
    click Output "https://github.com/melroyanthony/provet/blob/main/solution/consultation1_discharge.json"
    click Dockerfile "https://github.com/melroyanthony/provet/tree/main/Dockerfile"
    click Compose "https://github.com/melroyanthony/provet/blob/main/docker-compose.yml"
    click Scripts "https://github.com/melroyanthony/provet/blob/main/scripts/setup_cli.sh"
    click Tests "https://github.com/melroyanthony/provet/blob/main/pytest.ini"

    %% Styles
    classDef interface fill:#9f6,stroke:#396,stroke-width:2px
    classDef core fill:#6cf,stroke:#039,stroke-width:2px
    classDef utils fill:#6cf,stroke:#036,stroke-width:2px
    classDef data fill:#ff9,stroke:#cc3,stroke-width:2px
    classDef external fill:#f96,stroke:#d63,stroke-width:2px
    classDef deploy fill:#ccc,stroke:#888,stroke-width:2px
```
