Daily Journal Prompt Generator - Web Application

A modern web application for generating AI-powered journal writing prompts, refactored from a CLI tool to a full web stack with FastAPI backend and Astro frontend.

✨ Features

• AI-Powered Prompt Generation: Uses DeepSeek/OpenAI API to generate creative writing prompts
• Smart History System: 60-prompt cyclic buffer to avoid repetition and steer themes
• Prompt Pool Management: Caches prompts for offline use with automatic refilling
• Theme Feedback System: AI analyzes your preferences to improve future prompts
• Modern Web Interface: Responsive design with intuitive UI
• RESTful API: Fully documented API for programmatic access
• Docker Support: Easy deployment with Docker and Docker Compose

🏗️ Architecture

Backend (FastAPI)

• Framework: FastAPI with async/await support
• API Documentation: Automatic OpenAPI/Swagger documentation
• Data Persistence: JSON file storage with async file operations
• Services: Modular architecture with clear separation of concerns
• Validation: Pydantic models for request/response validation
• Error Handling: Comprehensive error handling with custom exceptions

Frontend (Astro + React)

• Framework: Astro with React components for interactivity
• Styling: Custom CSS with modern design system
• Responsive Design: Mobile-first responsive layout
• API Integration: Proxy configuration for seamless backend communication
• Component Architecture: Reusable React components

Infrastructure

• Docker: Multi-container setup with development and production configurations
• Docker Compose: Orchestration for local development
• Nginx: Reverse proxy for frontend serving
• Health Checks: Container health monitoring

📁 Project Structure

daily-journal-prompt/
├── backend/                    # FastAPI backend
│   ├── app/
│   │   ├── api/v1/            # API endpoints
│   │   ├── core/              # Configuration, logging, exceptions
│   │   ├── models/            # Pydantic models
│   │   └── services/          # Business logic services
│   ├── main.py                # FastAPI application entry point
│   └── requirements.txt       # Python dependencies
├── frontend/                  # Astro frontend
│   ├── src/
│   │   ├── components/        # React components
│   │   ├── layouts/           # Layout components
│   │   ├── pages/             # Astro pages
│   │   └── styles/            # CSS styles
│   ├── astro.config.mjs       # Astro configuration
│   └── package.json           # Node.js dependencies
├── data/                      # Data storage (mounted volume)
│   ├── prompts_historic.json  # Historic prompts
│   ├── prompts_pool.json      # Prompt pool
│   ├── feedback_words.json    # Feedback words with weights
│   ├── feedback_historic.json # Historic feedback
│   ├── ds_prompt.txt          # Prompt template
│   ├── ds_feedback.txt        # Feedback template
│   └── settings.cfg           # Application settings
├── docker-compose.yml         # Docker Compose configuration
├── backend/Dockerfile         # Backend Dockerfile
├── frontend/Dockerfile        # Frontend Dockerfile
├── .env.example              # Environment variables template
├── API_DOCUMENTATION.md      # API documentation
├── AGENTS.md                 # Project planning and architecture
└── README.md                 # This file

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• Docker and Docker Compose (optional)
• API key from DeepSeek or OpenAI

Option 1: Docker (Recommended)

1. Clone and setup

   git clone <repository-url>
   cd daily-journal-prompt
   cp .env.example .env
   

2. Edit .env file

   # Add your API key
   DEEPSEEK_API_KEY=your_api_key_here
   # or
   OPENAI_API_KEY=your_api_key_here
   

3. Start with Docker Compose

   docker-compose up --build
   

4. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

Option 2: Manual Setup

Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Set environment variables
export DEEPSEEK_API_KEY=your_api_key_here
# or
export OPENAI_API_KEY=your_api_key_here

# Run the backend
uvicorn main:app --reload

Frontend Setup

cd frontend
npm install
npm run dev

📚 API Usage

The API provides comprehensive endpoints for prompt management:

Basic Operations

# Draw prompts from pool
curl http://localhost:8000/api/v1/prompts/draw

# Fill prompt pool
curl -X POST http://localhost:8000/api/v1/prompts/fill-pool

# Get statistics
curl http://localhost:8000/api/v1/prompts/stats

Interactive Documentation

Access the automatic API documentation at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🔧 Configuration

Environment Variables

Create a .env file based on .env.example:

# Required: At least one API key
DEEPSEEK_API_KEY=your_deepseek_api_key
OPENAI_API_KEY=your_openai_api_key

# Optional: Customize behavior
API_BASE_URL=https://api.deepseek.com
MODEL=deepseek-chat
DEBUG=false
CACHED_POOL_VOLUME=20
NUM_PROMPTS_PER_SESSION=6

Application Settings

Edit data/settings.cfg to customize:

• Prompt length constraints
• Number of prompts per session
• Pool volume targets

🐛 Troubleshooting

Docker Permission Issues

If you encounter permission errors when running Docker containers:

1. Check directory permissions:

   ls -la data/
   

   The data/ directory should be readable/writable by your user (UID 1000 typically).

2. Fix permissions (if needed):

   chmod 700 data/
   chown -R $(id -u):$(id -g) data/
   

3. Verify Docker user matches host user: The Dockerfile creates a user with UID 1000. If your host user has a different UID:

   # Check your UID
   id -u
   
   # Update Dockerfile to match your UID
   # Change: RUN useradd -m -u 1000 appuser
   # To: RUN useradd -m -u YOUR_UID appuser
   

npm Build Errors

If you see npm ci errors:

• The Dockerfile uses npm install instead of npm ci for development
• For production, generate a package-lock.json file first:

  cd frontend
  npm install
  

API Connection Issues

If the backend can't connect to AI APIs:

1. Verify your API key is set in .env
2. Check network connectivity
3. Ensure the API service is available

🧪 Testing

Run the backend tests:

python test_backend.py

🐳 Docker Development

Development Mode

# Hot reload for both backend and frontend
docker-compose up --build

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Useful Commands

# Rebuild specific service
docker-compose build backend

# Run single service
docker-compose up backend

# Execute commands in container
docker-compose exec backend python -m pytest

🔄 Migration from CLI

The web application maintains full compatibility with the original CLI data format:

1. Data Files: Existing JSON files are automatically used
2. Templates: Same prompt and feedback templates
3. Settings: Compatible settings.cfg format
4. Functionality: All CLI features available via API

📊 Features Comparison

Feature	CLI Version	Web Version
Prompt Generation	✅	✅
Prompt Pool	✅	✅
History Management	✅	✅
Theme Feedback	✅	✅
Web Interface	❌	✅
REST API	❌	✅
Docker Support	❌	✅
Multi-user Ready	❌	✅ (future)
Mobile Responsive	❌	✅

🛠️ Development

Backend Development

cd backend
# Install development dependencies
pip install -r requirements.txt

# Run with hot reload
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Run tests
python test_backend.py

Frontend Development

cd frontend
# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

Code Structure

• Backend: Follows FastAPI best practices with dependency injection
• Frontend: Uses Astro islands architecture with React components
• Services: Async/await pattern for I/O operations
• Error Handling: Comprehensive error handling at all levels

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Development Guidelines

• Follow PEP 8 for Python code
• Use TypeScript for React components when possible
• Write meaningful commit messages
• Update documentation for new features
• Add tests for new functionality

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with FastAPI
• Frontend with Astro
• AI integration with OpenAI and DeepSeek
• Icons from Font Awesome

📞 Support

• Issues: Use GitHub Issues for bug reports and feature requests
• Documentation: Check API_DOCUMENTATION.md for API details
• Examples: See the test files for usage examples

🚀 Deployment

Cloud Platforms

• Render: One-click deployment with Docker
• Railway: Easy deployment with environment management
• Fly.io: Global deployment with edge computing
• AWS/GCP/Azure: Traditional cloud deployment

Deployment Steps

1. Set environment variables
2. Build Docker images
3. Configure database (if migrating from JSON)
4. Set up reverse proxy (nginx/caddy)
5. Configure SSL certificates
6. Set up monitoring and logging

---

Happy Journaling! 📓✨