How sanjith-v/hippocratic works
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.