# sanjith-v/hippocratic architecture

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

- Interactive diagram: https://gitdiagram.com/sanjith-v/hippocratic
- Repository: https://github.com/sanjith-v/hippocratic

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Hippocratic AI — Bedtime Story Generator”) built with Python/Flask on the backend and simple HTML/CSS/JavaScript templates on the frontend.
- It exposes a web interface where end users (kids or parents) request either a short story or a multi-arc story, optionally tweaking between chapters. The backend orchestrates calls to OpenAI’s GPT models.

##### File Structure Analysis
- Top-level files:
– webapp.py / app.py / main.py: Flask application entry points (flask run / Gunicorn).
– pipeline.py: Orchestrates story generation workflows (short vs. multi-arc, tweaks).
– llm.py: Encapsulates logic for calling OpenAI’s GPT API.
– prompts.py: Holds template strings / prompt builders used by llm.py.
– templates/index.html: Single-page UI with form inputs and a spinner overlay.
– Procfile & runtime.txt: Heroku deployment config; Gunicorn entry.
– requirements.txt: Python dependencies (Flask, OpenAI SDK, python-dotenv, etc.).
- No persistent database: state is kept in session or passed through API calls.

##### README Insights
- Tech stack: Frontend (Flask templates + minimal JS/CSS), Backend (Flask), LLM (OpenAI gpt-3.5-turbo), Hosting (Heroku + Gunicorn).

##### Main Components & Their Interactions
A. Browser / Frontend UI
- Renders index.html
- Captures user inputs (mode, tweaks)
- Shows loading spinner during generation
→ Sends HTTP requests to Flask endpoints.

B. Web Server (Flask + Gunicorn on Heroku)
- Entry point: webapp.py (or app.py/main.py)
- Defines routes:
- GET / → serve index.html
- POST /generate → invoke pipeline
- Manages sessions / secret key for CSRF and environment loading.

C. Story Generation Pipeline (pipeline.py)
- Receives user request parameters
- Selects short-story or multi-arc logic
- Applies any user tweaks between chapters
- Coordinates calls to the LLM client

D. LLM Client (llm.py + prompts.py)
- prompts.py stores prompt templates and helpers
- llm.py builds the final prompt, calls OpenAI API, parses response
- Returns clean (markdown-stripped) title and story text

E. External Service
- OpenAI API (gpt-3.5-turbo) over HTTPS
- Requires OPENAI_API_KEY

F. Hosting Layer
- Heroku dyno
- Gunicorn WSGI server launching Flask app
- Configured via Procfile

##### Architectural Patterns & Design Principles
- Clear separation of concerns:
- Routing layer (Flask/webapp.py)
- Business logic layer (pipeline.py)
- Integration layer (llm.py + prompts.py)
- Modular code that can be tested independently (e.g., pipeline logic is pure Python).
- Stateless interactions: each HTTP request triggers a fresh pipeline run.
- Environment-driven configuration for API keys and secrets.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        UB["User Browser"]:::frontend
    end

    %% Hosting Layer
    subgraph "Hosting (Heroku Dyno)"
        GC["Gunicorn WSGI Server"]:::hosting
        subgraph "Flask Service"
            RL["Routing Layer\n(GET /, POST /generate)"]:::backend
            PS["Pipeline Service"]:::backend
            LC["LLM Client"]:::backend
            PT["Prompt Templates"]:::backend
        end
        ProcfileNode["Procfile"]:::hosting
        RuntimeNode["runtime.txt"]:::hosting
    end

    %% External Services
    OA["OpenAI API\n(gpt-3.5-turbo)"]:::external

    %% Docs & Config
    subgraph "Project Docs & Config"
        ReqNode["requirements.txt"]:::docs
        ReadmeNode["README.md"]:::docs
    end

    %% Data Flow
    UB -->|"HTTP POST /generate\n(mode, tweaks)"| RL
    RL -->|"invokes pipeline\n(session, env)"| PS
    PS -->|"builds prompt text"| PT
    PT -->|"template data"| PS
    PS -->|"calls LLM Client"| LC
    LC -->|"HTTPS request\n(OpenAI_API_KEY)"| OA
    OA -->|"response JSON\nstory text"| LC
    LC -->|"parsed title & story"| PS
    PS -->|"result JSON"| RL
    RL -->|"HTTP response\n(rendered HTML)"| UB

    %% Hosting Connectivity
    GC --> RL

    %% Click Events
    click UB "https://github.com/sanjith-v/hippocratic/blob/main/templates/index.html"
    click RL "https://github.com/sanjith-v/hippocratic/blob/main/webapp.py"
    click PS "https://github.com/sanjith-v/hippocratic/blob/main/pipeline.py"
    click LC "https://github.com/sanjith-v/hippocratic/blob/main/llm.py"
    click PT "https://github.com/sanjith-v/hippocratic/blob/main/prompts.py"
    click ProcfileNode "https://github.com/sanjith-v/hippocratic/tree/main/Procfile"
    click RuntimeNode "https://github.com/sanjith-v/hippocratic/blob/main/runtime.txt"
    click ReqNode "https://github.com/sanjith-v/hippocratic/blob/main/requirements.txt"
    click ReadmeNode "https://github.com/sanjith-v/hippocratic/blob/main/README.md"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#B2FAB4,stroke:#0A0,stroke-width:1px
    classDef external fill:#F9D976,stroke:#F39C12,stroke-width:1px
    classDef hosting fill:#D3D3D3,stroke:#888,stroke-width:1px
    classDef docs fill:#FFFFFF,stroke:#000,stroke-dasharray:5 5
```
