# Daily Journal Prompt Generator - Webapp Refactoring Plan
## Overview
Refactor the existing Python CLI application into a modern web application with FastAPI backend and a lightweight frontend. The system will maintain all existing functionality while providing a web-based interface for easier access and better user experience.
- **Configuration**: `.env` file for API keys, `settings.cfg` for app settings
- **Functionality**:
1. AI-powered prompt generation using OpenAI-compatible APIs
2. Smart repetition avoidance with 60-prompt history buffer
3. Prompt pool system for offline usage
4. Interactive CLI with rich formatting
### Key Features to Preserve
1. AI prompt generation with history awareness
2. Prompt pool management (fill, draw, stats)
3. Configuration via environment variables
4. JSON-based data persistence
5. All existing prompt generation logic
As the user discards prompts, the themes will be very slowly steered, so it's okay to take some inspiration from the history.
## Proposed Web Application Architecture
### Backend: FastAPI
**Rationale**: FastAPI provides async capabilities, automatic OpenAPI documentation, and excellent performance. It's well-suited for AI API integrations.
**Components**:
1.**API Endpoints**:
-`GET /api/prompts/draw` - Draw prompts from pool
-`POST /api/prompts/fill-pool` - Fill prompt pool using AI
-`GET /api/prompts/stats` - Get pool and history statistics
-`GET /api/prompts/history` - Get prompt history
-`POST /api/prompts/select/{prompt_id}` - Select a prompt for journaling
2.**Core Services**:
- PromptGeneratorService (adapted from existing logic)
The refactoring from CLI to webapp will significantly improve accessibility and user experience while maintaining all existing functionality. The proposed architecture using FastAPI + Astro provides a modern, performant, and maintainable foundation for future enhancements.
The phased approach allows for incremental development with clear milestones and risk mitigation at each step.
1.**Complete Backend API** with all original CLI functionality
2.**Modern Frontend** with responsive design and interactive components
3.**Docker Configuration** for easy deployment and development
4.**Comprehensive Documentation** including API docs and setup instructions
5.**Testing Infrastructure** to ensure reliability
### Key Technical Achievements
- **Modular Service Architecture**: Clean separation of concerns
- **Async Operations**: Full async/await support for better performance
- **Error Handling**: Comprehensive error handling with custom exceptions
- **Data Compatibility**: Full backward compatibility with existing CLI data
- **Development Experience**: Hot reload, health checks, and easy setup
### Ready for Use
The web application is now ready for:
- Local development with Docker or manual setup
- Testing with existing prompt data
- Deployment to cloud platforms
- Further feature development
### Files Created/Modified
```
Created:
- backend/ (complete FastAPI application)
- frontend/ (complete Astro + React application)
- data/ (data directory with all existing files)
- docker-compose.yml
- .env.example
- API_DOCUMENTATION.md
- test_backend.py
- run_webapp.sh
Updated:
- README.md (webapp documentation)
- AGENTS.md (this file, with completion status)
```
The Phase 1 implementation successfully transforms the CLI tool into a modern web application while preserving all existing functionality and data compatibility.
**Problem**: The original Docker build was failing with the error:
```
npm error The `npm ci` command can only install with an existing package-lock.json or
npm error npm-shrinkwrap.json with lockfileVersion >= 1. Run an install with npm@5 or
npm error later to generate a package-lock.json file, then try again.
```
**Solution**: Updated the frontend Dockerfile to use `npm install` instead of `npm ci` since no package-lock.json file exists yet. The updated Dockerfile now works correctly:
```dockerfile
# Install dependencies
# Use npm install for development (npm ci requires package-lock.json)
RUN npm install
```
**Verification**: Docker build now completes successfully and the frontend container can be built and run without errors.
## Docker Permission Error Resolution
**Problem**: The backend container was failing with the error:
**Solution**: Fixed the path calculation to use the configuration-based approach:
```python
# Correct calculation using settings
from pathlib import Path
from app.core.config import settings
data_dir = Path(settings.DATA_DIR) # 'data' -> resolves to '/app/data' in container
data_dir.mkdir(exist_ok=True)
```
**Additional Considerations**:
1.**User Permissions**: The Dockerfile creates a non-root user `appuser` with UID 1000, which matches the typical host user UID for better volume permission compatibility.
2.**Volume Mount**: The docker-compose.yml mounts `./data:/app/data` ensuring data persistence.
3.**Directory Permissions**: The host `data/` directory has permissions `700` (owner only), but since the container user has the same UID (1000), it can access the directory.
**Verification**:
- Docker builds complete successfully for both backend and frontend
- Backend container starts without permission errors
- API endpoints respond correctly
- Health check endpoint returns `{"status": "healthy"}`
- FastAPI documentation endpoints (`/docs` and `/redoc`) are now always enabled
## FastAPI Documentation Endpoints Fix
**Problem**: FastAPI's built-in documentation endpoints (`/docs` and `/redoc`) were not working because they were only enabled when `DEBUG=true`.
**Root Cause**: In `backend/main.py`, the documentation endpoints were conditionally enabled:
```python
docs_url="/docs" if settings.DEBUG else None,
redoc_url="/redoc" if settings.DEBUG else None,
```
**Solution**: Removed the conditional logic to always enable documentation endpoints:
```python
docs_url="/docs",
redoc_url="/redoc",
```
**Verification**:
-`/docs` endpoint returns HTTP 200 with Swagger UI
-`/redoc` endpoint returns HTTP 200 with ReDoc documentation
Backend and backend docs seem to be in a good state.
Let us focus on frontend for a bit.
Task 1:
There are UI elements which shift on mouseover. This is bad design.
Task 2:
The default page should show just the prompt in the most recent position in history. It currently does a draw from the pool, or possibly displays the most recent draw action. Drawing from the pool should only happen when requested by the user.
On the default page there should be some sort of indication of how full the pool is. A simple graphical element would be nice. It should only show one writing prompt.
Task 3:
Check whether the UI buttons to refill the pool and to draw from the pool have working functionality.
Task 4:
Change the default number drawn from the pool to 3.
