# ainnov/draw-your-day architecture

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

- Interactive diagram: https://gitdiagram.com/ainnov/draw-your-day
- Repository: https://github.com/ainnov/draw-your-day

## Overview

##### Project type and purpose
- Purpose: Users write diary entries via a Streamlit frontend; the system uses a FastAPI backend, a PostgreSQL database, a QLoRA‑fine‑tuned LLaMA‑2 model for text understanding, and Stable Diffusion 1.5 for illustration generation.

##### File structure
- Top‑level files:
- app.py, main.py, server.py – entry points for Streamlit and FastAPI.
- create_tables.py – DB initialization.
- retrieval.py – likely the RAG retrieval logic.
- database/ – contains database.py (session/config) and models.py (ORM definitions).
- pages/ – Streamlit page modules (login, logout, diary_new, diary_list, cookie_manager).
- assets/ – images used in the README and web UI.
- template/ – prompt templates for RAG and full‑context queries.
- data/raw/ – raw JSON training data.
- data/ – example diaries used for local testing or evaluation.

##### README for additional insights
- Tech stack: FastAPI, StreamLit, PostgreSQL, QLoRA‑LLaMA2, Stable Diffusion.
- Two pipelines:
- Front/Backend pipeline (user ↔ frontend ↔ API ↔ DB & AI).
- AI pipeline (retrieval → LLaMA2 inference → Stable Diffusion).

##### Main components and their interactions
a. Frontend (Streamlit)
- pages/login, pages/logout handle auth state via cookies.
- pages/diary_new collects text input and submits it to the backend.
- pages/diary_list shows past entries and generated images.
- pages/cookie_manager manages session cookies.
b. Backend (FastAPI server.py / main.py)
- Exposes REST endpoints for login, logout, submit diary, list diaries.
- Orchestrates calls to the database layer and the AI pipeline.
c. Database (PostgreSQL via database/database.py & models.py)
- Stores user credentials, diary entries, and metadata (timestamps, image URLs).
- create_tables.py bootstraps the schema.
d. AI Pipeline
1. Retrieval (retrieval.py)
– Takes a new diary entry, queries Vector DB or JSON store (data/raw) for context.
2. LLaMA2 QLoRA inference
– Uses prompt templates (template/*.txt) to generate an image prompt.
3. Stable Diffusion 1.5
– Takes the generated prompt and renders an illustration (via a local pipeline, no external API).
e. Assets & Templates
– template/ holds the text‑to‑prompt templates for RAG and full context.

##### Architectural patterns and design principles
- Monolithic Python service but logically separated into frontend, API, DB, and AI sub‑modules.
- Clear separation of concerns: Streamlit handles UI, FastAPI handles business logic, database layer handles persistence, AI pipeline handles model inference.
- RAG pattern in retrieval.py, prompting pattern via template files, single‑host inference to minimize VRAM usage.

##### Detail and clarity
- Data flows end‑to‑end (user diary → DB & prompt → LLaMA2 → Stable Diffusion → image URL back to UI).
- Callouts for configuration (Streamlit config in .streamlit/config.toml, create_tables.py run step).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and UI Layer
    User["User / Browser"]:::external
    subgraph "Frontend (Streamlit)" 
        style Frontend fill:#CFE2F3,stroke:#6FA8DC
        App["Streamlit App (app.py)"]:::frontend
        Login["Login Page"]:::frontend
        Logout["Logout Page"]:::frontend
        DiaryNew["New Diary Entry Page"]:::frontend
        DiaryList["Diary List Page"]:::frontend
        CookieMgr["Cookie Manager"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)" 
        style Backend fill:#D9EAD3,stroke:#93C47D
        API["API Server (server.py)"]:::backend
        Main["App Launcher (main.py)"]:::backend
    end

    %% Database Layer
    subgraph "Database (PostgreSQL)" 
        style Database fill:#FCE5CD,stroke:#E69138
        ORM["ORM Models (models.py)"]:::db
        DBConfig["DB Config (database.py)"]:::db
        InitDB["Schema Init (create_tables.py)"]:::db
        Postgres["PostgreSQL"]:::db
    end

    %% AI Pipeline
    subgraph "AI Pipeline" 
        style AI fill:#D9D2E9,stroke:#8E7CC3
        Retrieval["Retrieval Logic (retrieval.py)"]:::ai
        LLaMA["LLaMA2 QLoRA Inference"]:::ai
        SD["Stable Diffusion 1.5"]:::ai
    end

    %% File Storage & Templates
    subgraph "File Storage & Templates"
        style Storage fill:#EDEDED,stroke:#999999
        Templates["Prompt Templates"]:::storage
        RawData["Retrieval Corpus (DYD_newtrain.json)"]:::storage
        Eval1["Eval Diary 1"]:::storage
        Eval2["Eval Diary 2"]:::storage
        Assets["Static Assets"]:::storage
    end

    %% Connections
    User -->|"Interacts via HTTP"| App
    App -->|"POST /api/diary / GET /api/diaries"| API
    API -->|"ORM queries"| ORM
    API -->|"DB sessions"| DBConfig
    ORM -->|"creates tables"| InitDB
    ORM -->|"stores data in"| Postgres
    API -->|"calls"| Retrieval
    Retrieval -->|"SELECT context from"| RawData
    Retrieval -->|"uses prompt"| Templates
    Retrieval -->|"passes to"| LLaMA
    LLaMA -->|"generates image prompt"| SD
    SD -->|"renders image"| Assets
    SD -->|"returns URL"| API
    API -->|"returns JSON / URLs"| App

    %% File reads/writes (dashed lines)
    App -.->|"reads images"| Assets
    API -.->|"reads templates"| Templates

    %% Click Events
    click App "https://github.com/ainnov/draw-your-day/blob/app/app.py"
    click Login "https://github.com/ainnov/draw-your-day/blob/app/pages/login.py"
    click Logout "https://github.com/ainnov/draw-your-day/blob/app/pages/logout.py"
    click DiaryNew "https://github.com/ainnov/draw-your-day/blob/app/pages/diary_new.py"
    click DiaryList "https://github.com/ainnov/draw-your-day/blob/app/pages/diary_list.py"
    click CookieMgr "https://github.com/ainnov/draw-your-day/blob/app/pages/cookie_manager.py"
    click API "https://github.com/ainnov/draw-your-day/blob/app/server.py"
    click Main "https://github.com/ainnov/draw-your-day/blob/app/main.py"
    click ORM "https://github.com/ainnov/draw-your-day/blob/app/database/models.py"
    click DBConfig "https://github.com/ainnov/draw-your-day/blob/app/database/database.py"
    click InitDB "https://github.com/ainnov/draw-your-day/blob/app/create_tables.py"
    click Retrieval "https://github.com/ainnov/draw-your-day/blob/app/retrieval.py"
    click Templates "https://github.com/ainnov/draw-your-day/tree/app/template/"
    click RawData "https://github.com/ainnov/draw-your-day/blob/app/data/raw/DYD_newtrain.json"
    click Eval1 "https://github.com/ainnov/draw-your-day/blob/app/data/evaluation_diary1.txt"
    click Eval2 "https://github.com/ainnov/draw-your-day/blob/app/data/evaluation_diary2.txt"
    click Assets "https://github.com/ainnov/draw-your-day/tree/app/assets/"

    %% Classes
    classDef frontend fill:#CFE2F3,stroke:#6FA8DC;
    classDef backend fill:#D9EAD3,stroke:#93C47D;
    classDef db fill:#FCE5CD,stroke:#E69138;
    classDef ai fill:#D9D2E9,stroke:#8E7CC3;
    classDef storage fill:#EDEDED,stroke:#999999;
    classDef external fill:#FFFFFF,stroke:#000000,stroke-dasharray: 5 5;
```
