daily-journal-prompt/FUNCTIONAL_README.md

Daily Journal Prompt Generator - Functional Overview

📖 What This Application Does

This is a web application that helps writers and journalers by generating creative writing prompts. It uses AI (DeepSeek or OpenAI) to create unique prompts, remembers what prompts you've seen before to avoid repetition, and learns from your preferences to generate better prompts over time.

Core Features:

• AI-Powered Prompt Generation: Creates unique journal writing prompts using AI
• Smart Memory: Remembers the last 60 prompts you've seen to avoid repetition
• Prompt Pool: Stores generated prompts so you can use them even without internet
• Theme Learning: Learns what themes you like/dislike to improve future prompts
• Web Interface: Easy-to-use website accessible from any device

🏗️ How It Works - System Flow

1. User Opens the Website

• User visits http://localhost:3000 (or your deployed URL)
• The frontend loads and shows the most recent prompt from history

2. Getting New Prompts

• User clicks "Draw 3 New Prompts"
• Backend selects 3 random prompts from the pool
• If pool is low (< 20 prompts), system suggests refilling it

3. Selecting a Prompt

• User clicks on one of the 3 displayed prompts
• User clicks "Use Selected Prompt"
• The selected prompt is added to history (position 0, most recent)
• History shifts - oldest prompt (position 59) is removed if history is full

4. Refilling the Prompt Pool

• When pool is low, user clicks "Fill Prompt Pool"
• System immediately starts refilling pool using AI
• While pool refills, user rates 6 "theme words" (e.g., "adventure", "reflection")
• User adjusts weights (0-6) for each theme word:
  • 0 = Ignore this theme
  • 3 = Neutral (default)
  • 6 = Strongly prefer this theme
• After rating, system generates new theme words for future use

5. Theme Learning Process

• System maintains 30 theme words in a "cyclic buffer"
• Positions 0-5: Queued words - shown to user for rating
• Positions 6-11: Active words - used for AI prompt generation
• Positions 12-29: Historic words - older theme words
• When user rates queued words, new words are generated and inserted at position 0

🗂️ File Structure & Purpose

Data Files (in data/ directory)

• prompts_historic.json - Last 60 prompts shown to user (cyclic buffer)
• prompts_pool.json - Available prompts ready for use (target: 20)
• feedback_historic.json - 30 theme words with weights (cyclic buffer)
• ds_prompt.txt - Template for AI prompt generation
• ds_feedback.txt - Template for AI theme word generation
• settings.cfg - Application settings (prompt length, counts, etc.)

Backend Files (in backend/ directory)

• main.py - FastAPI application entry point
• app/services/data_service.py - Reads/writes JSON files
• app/services/prompt_service.py - Main logic for prompt operations
• app/services/ai_service.py - Communicates with AI APIs
• app/api/v1/endpoints/prompts.py - API endpoints for prompts
• app/api/v1/endpoints/feedback.py - API endpoints for theme learning
• app/models/prompt.py - Data models for prompts and responses
• app/core/config.py - Configuration and settings

Frontend Files (in frontend/ directory)

• src/pages/index.astro - Main page
• src/components/PromptDisplay.jsx - Shows prompts and handles selection
• src/components/StatsDashboard.jsx - Shows pool/history statistics
• src/components/FeedbackWeighting.jsx - Theme word rating interface
• src/layouts/Layout.astro - Page layout with header/footer
• src/styles/global.css - CSS styles

Configuration Files

• .env - API keys and environment variables (create from .env.example)
• docker-compose.yml - Runs both backend and frontend together
• backend/Dockerfile - Backend container configuration
• frontend/Dockerfile - Frontend container configuration

🔄 Data Flow Diagrams

Prompt Flow:

User Request → Draw from Pool → Select Prompt → Add to History
      ↓              ↓               ↓              ↓
   Frontend      Backend         Backend        Backend
      ↓              ↓               ↓              ↓
   Display      Check Pool      Update Pool   Update History

Theme Learning Flow:

User Rates Words → Update Weights → Generate New Words → Fill Pool
       ↓                ↓                ↓                ↓
  Frontend          Backend           Backend          Backend
       ↓                ↓                ↓                ↓
 Show Weights     Save to JSON      Call AI API     Generate Prompts

🛠️ Technologies Explained Simply

FastAPI (Backend)

• What it is: A modern Python web framework for building APIs
• Why we use it: Fast, easy to use, automatically creates API documentation
• Simple analogy: Like a restaurant waiter - takes orders (requests) from customers (frontend) and brings food (responses) from the kitchen (AI/service)

Astro (Frontend)

• What it is: A web framework for building fast websites
• Why we use it: Good performance, can use React components when needed
• Simple analogy: Like a book - static pages (Astro) with some interactive pop-ups (React components)

React Components

• What they are: Reusable pieces of interactive web interface
• Why we use them: For interactive parts like prompt selection and theme rating
• Where used: PromptDisplay.jsx, StatsDashboard.jsx, FeedbackWeighting.jsx

Docker & Docker Compose

• What they are: Tools to package and run applications in containers
• Why we use them: Makes setup easy - runs everything with one command
• Simple analogy: Like shipping containers - everything needed is packed together and runs the same way everywhere

📊 Key Concepts Explained

Cyclic Buffer

• What: A fixed-size list where new items push out old ones
• Example: History holds 60 prompts. When #61 arrives, #1 is removed
• Why: Prevents unlimited growth, ensures recent data is prioritized

Prompt Pool

• What: A collection of pre-generated prompts
• Size: Target is 20 prompts
• Purpose: Allows using prompts without waiting for AI generation

Theme Words & Weights

• Theme Words: Words like "adventure", "reflection", "memory" that guide AI
• Weights: Numbers 0-6 that tell AI how much to use each theme
• Flow: User rates words → Weights are saved → AI uses weights for future prompts

API Endpoints

• What: URLs that the frontend calls to get data or perform actions
• Examples:
  • GET /api/v1/prompts/draw - Get prompts from pool
  • POST /api/v1/prompts/fill-pool - Refill prompt pool
  • GET /api/v1/feedback/queued - Get theme words for rating

🚀 Getting Started - Simple Version

1. Copy environment file:

cp .env.example .env

2. Edit .env file:

Add your AI API key (get from DeepSeek or OpenAI):

DEEPSEEK_API_KEY=your_key_here

3. Run with Docker:

docker-compose up --build

4. Open in browser:

• Website: http://localhost:3000
• API docs: http://localhost:8000/docs

🔧 Common Operations

Using the Application:

1. Get prompts: Click "Draw 3 New Prompts"
2. Select one: Click a prompt, then "Use Selected Prompt"
3. Refill pool: Click "Fill Prompt Pool" when pool is low
4. Rate themes: Adjust sliders for theme words (0-6)

Checking Status:

• Pool status: Shown as progress bar on Fill button
• History count: Shown in Stats Dashboard
• Theme words: Click "Fill Prompt Pool" to see current themes

Data Files Location:

All data is saved in the data/ directory:

• Prompts you've seen: prompts_historic.json
• Available prompts: prompts_pool.json
• Theme preferences: feedback_historic.json

❓ Frequently Asked Questions

Q: Where do prompts come from?

A: From AI (DeepSeek/OpenAI) using the template in ds_prompt.txt

Q: How does it avoid repeating prompts?

A: It keeps 60 most recent prompts in history and avoids those

Q: What happens if I rate a theme word 0?

A: That theme will be ignored in future prompt generation

Q: Can I use it without internet?

A: Yes, if the pool has prompts. AI calls need internet.

Q: How do I reset everything?

A: Delete files in data/ directory (except templates)

📈 Understanding the Numbers

History (60 prompts):

• Position 0: Most recent prompt (shown on main page)
• Position 59: Oldest prompt (will be removed next)
• Full when: 60 prompts stored

Pool (target: 20 prompts):

• "Low": Less than 20 prompts
• "Full": 20+ prompts available
• Drawn: 3 prompts at a time

Theme Words (30 words):

• Queued (0-5): Shown for rating (6 words)
• Active (6-11): Used for prompt generation (6 words)
• Historic (12-29): Older words (18 words)

🔍 Troubleshooting Common Issues

"No Prompts Available"

• Check if prompts_pool.json has prompts
• Try clicking "Fill Prompt Pool"
• Check API key in .env file

"Permission Denied" in Docker

• Check data/ directory permissions
• Try: chmod 700 data/

Website Not Loading

• Wait 8 seconds after docker-compose up
• Check if containers are running: docker-compose ps
• Check logs: docker-compose logs

AI Not Responding

• Verify API key in .env
• Check internet connection
• Try different AI provider (DeepSeek vs OpenAI)

📝 Key Configuration Settings

In settings.cfg:

• num_prompts = 3 - Number of prompts drawn at once
• prompt_min_length = 100 - Minimum prompt length
• prompt_max_length = 300 - Maximum prompt length

In .env:

• DEEPSEEK_API_KEY or OPENAI_API_KEY - AI provider key
• API_BASE_URL - AI service URL (default: DeepSeek)
• MODEL - AI model to use (default: deepseek-chat)

🎯 Summary - What Makes This Special

1. Smart Memory: Remembers what you've seen to avoid repetition
2. Theme Learning: Gets better at prompts you like over time
3. Offline Ready: Pool system works without constant AI calls
4. Simple Interface: Clean, easy-to-use web interface
5. Self-Contained: Runs everything locally with Docker

This application combines AI creativity with user preferences to create a personalized journaling experience that improves the more you use it.