# qnity001/coffee-break architecture

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

- Interactive diagram: https://gitdiagram.com/qnity001/coffee-break
- Repository: https://github.com/qnity001/coffee-break

## Overview

##### Project type and purpose
- This is a full-stack mental-health companion for students:
- A static informational site (HTML/CSS/JS) hosting landing pages (“about”, “resources”, “coffee”)
- A Flask backend under the `AI/` folder providing the “Milo” chat interface
- An external dependency on the OpenAI API to generate empathetic chatbot responses

##### File structure
- Top-level directories and files:
- `index.html`, `about/`, `resources/`, `coffee/`, plus global `script.js` and `style.css` → static site
- `AI/` → Flask application
– `app.py` (controller/routes)
– `system_instruction.txt` (prompt template)
– `data.json` (resource metadata)
– `requirements.txt`
– `templates/` (Jinja2 views: `bot.html`)
– `static/` (chat-UI assets: `app.js`, `stylebot.css`)
- Patterns: MVC‐style in Flask (templates = views, static assets = public, app.py = controller), static content served separately (via GitHub Pages or CDN)

##### Key insights from README
- Backend “handshake” between front end and Flask
- Rate-limit handling (delay logic) around OpenAI API
- Single-session memory stored in process (no persistent DB yet)

##### Main components
A. Web Client (Browser)
- Renders static pages (`index.html`, `about/…`, `resources/…`)
- Loads `script.js`/`style.css`
- On “Coffee” page, initializes chat widget (`app.js`)
B. Static-Site Host
- GitHub Pages or Nginx serving the entire `index.html`, `/about`, `/resources`, `/coffee` folder
C. Flask Backend
- `app.py`
- Route `GET /chat` → serves `templates/bot.html`
- Route `POST /api/message` → reads user message, loads `system_instruction.txt`, `data.json`, calls OpenAI API, returns response
- `templates/` + `static/` within `AI/`
D. Data Store (file‐based)
- `data.json` (resource metadata for in-chat suggestions)
- Future: relational/NoSQL DB for user sessions
E. External Service
- OpenAI API (GPT-based model)

##### Relationships & interactions
1. User’s browser requests `GET /coffee/index.html` from static host
2. Browser loads chat widget (`AI/static/app.js`) via script tag (could be proxied or fetched directly from backend host)
3. Client JS sends `POST /api/message` to Flask server with the user’s input
4. Flask server:
a. Reads `system_instruction.txt` + `data.json`
b. Calls OpenAI API over HTTPS
c. Receives chatbot reply
d. Returns JSON response to client
5. Browser receives JSON, updates DOM, displays chatbot message

##### Architectural patterns & design principles
- Separation of concerns: static site vs. API service
- MVC in backend (views, controllers)
- Single‐page mini-app for chat widget (modular JS)
- External dependency isolation (all OpenAI calls in one module)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Web Client (Browser)"]:::frontend

        subgraph "Static Site Host"
            direction TB
            StaticHost["Static-Site Host"]:::frontend
            subgraph "Static Content"
                direction TB
                idx["index.html"]:::frontend
                aboutPG["about/index.html"]:::frontend
                resPG["resources/index.html"]:::frontend
                coffeePG["coffee/index.html"]:::frontend
                gscr["script.js"]:::frontend
                gstl["style.css"]:::frontend
                ascr["about/script.js"]:::frontend
                astl["about/style.css"]:::frontend
                rscr["resources/script.js"]:::frontend
                rstl["resources/style.css"]:::frontend
            end
        end

        subgraph "Chat Widget Assets"
            direction TB
            appJs["app.js"]:::frontend
            styleBot["stylebot.css"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Flask["Flask App (app.py)"]:::backend
        Template["bot.html (view)"]:::backend
        Requirements["requirements.txt"]:::backend
        SystemInst["system_instruction.txt"]:::backend
        DataFile["data.json"]:::backend
    end

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

    %% Connections
    Browser -->|"HTTP GET /coffee/index.html"| StaticHost
    StaticHost -->|serves HTML/CSS/JS| Browser
    StaticHost -->|hosts| idx
    StaticHost -->|hosts| aboutPG
    StaticHost -->|hosts| resPG
    StaticHost -->|hosts| coffeePG
    StaticHost -->|hosts| gscr
    StaticHost -->|hosts| gstl
    StaticHost -->|hosts| ascr
    StaticHost -->|hosts| astl
    StaticHost -->|hosts| rscr
    StaticHost -->|hosts| rstl

    Browser -->|"loads app.js/stylebot.css"| appJs
    Browser -->|"loads app.js/stylebot.css"| styleBot

    Browser -->|"GET /chat"| Flask
    Flask -->|renders| Template
    Template -->|HTML response| Browser

    Browser -->|"POST /api/message"| Flask
    Flask -->|"reads prompt & metadata"| SystemInst
    Flask -->|"reads prompt & metadata"| DataFile
    Flask -->|"HTTPS call"| OpenAI
    OpenAI -->|"response"| Flask
    Flask -->|"JSON response"| Browser

    %% Click Events
    click idx "https://github.com/qnity001/coffee-break/blob/main//index.html"
    click aboutPG "https://github.com/qnity001/coffee-break/blob/main//about/about.html"
    click resPG "https://github.com/qnity001/coffee-break/blob/main//resources/index.html"
    click coffeePG "https://github.com/qnity001/coffee-break/blob/main//coffee/index.html"
    click gscr "https://github.com/qnity001/coffee-break/blob/main//script.js"
    click gstl "https://github.com/qnity001/coffee-break/blob/main//style.css"
    click ascr "https://github.com/qnity001/coffee-break/blob/main//about/script.js"
    click astl "https://github.com/qnity001/coffee-break/blob/main//about/style.css"
    click rscr "https://github.com/qnity001/coffee-break/blob/main//resources/script.js"
    click rstl "https://github.com/qnity001/coffee-break/blob/main//resources/style.css"
    click appJs "https://github.com/qnity001/coffee-break/blob/main/AI/static/app.js"
    click styleBot "https://github.com/qnity001/coffee-break/blob/main/AI/static/stylebot.css"
    click Flask "https://github.com/qnity001/coffee-break/blob/main/AI/app.py"
    click Template "https://github.com/qnity001/coffee-break/blob/main/AI/templates/bot.html"
    click Requirements "https://github.com/qnity001/coffee-break/blob/main/AI/requirements.txt"
    click SystemInst "https://github.com/qnity001/coffee-break/blob/main/AI/system_instruction.txt"
    click DataFile "https://github.com/qnity001/coffee-break/blob/main/AI/data.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;
```
