daily-journal-prompt/README.md

# 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**
   ```bash
   git clone <repository-url>
   cd daily-journal-prompt
   cp .env.example .env
   ```

2. **Edit .env file**
   ```bash
   # Add your API key
   DEEPSEEK_API_KEY=your_api_key_here
   # or
   OPENAI_API_KEY=your_api_key_here
   ```

3. **Start with Docker Compose**
   ```bash
   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
```bash
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
```bash
cd frontend
npm install
npm run dev
```

## 📚 API Usage

The API provides comprehensive endpoints for prompt management:

### Basic Operations
```bash
# 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`:

```env
# 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**:
   ```bash
   ls -la data/
   ```
   The `data/` directory should be readable/writable by your user (UID 1000 typically).

2. **Fix permissions** (if needed):
   ```bash
   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:
   ```bash
   # 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:
  ```bash
  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:
```bash
python test_backend.py
```

## 🐳 Docker Development

### Development Mode
```bash
# Hot reload for both backend and frontend
docker-compose up --build

# View logs
docker-compose logs -f

# Stop services
docker-compose down
```

### Useful Commands
```bash
# 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
```bash
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
```bash
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](https://fastapi.tiangolo.com/)
- Frontend with [Astro](https://astro.build/)
- AI integration with [OpenAI](https://openai.com/) and [DeepSeek](https://www.deepseek.com/)
- Icons from [Font Awesome](https://fontawesome.com/)

## 📞 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! 📓✨**