planning checkpoint next step in agents

AGENTS.md

@@ -1 +1,300 @@
-Empty AGENTS.md for planning webapp
+# 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.
+
+## Current Architecture Analysis
+
+### Existing CLI Application
+- **Language**: Python 3.7+
+- **Core Dependencies**: openai, python-dotenv, rich
+- **Data Storage**: JSON files (`prompts_historic.json`, `prompts_pool.json`)
+- **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)
+   - PromptPoolService (manages pool operations)
+   - HistoryService (manages 60-item cyclic buffer)
+   - AIClientService (OpenAI API integration)
+
+3. **Data Layer**:
+   - **Initial Approach**: Keep JSON file storage (`prompts_historic.json`, `prompts_pool.json`)
+   - **Docker Volume**: Mount `./data` directory to `/app/data` for persistent JSON storage
+   - **Future Evolution**: SQLite database migration path (optional later phase)
+   - **Rationale**: Maintains compatibility with existing CLI app, simple file-based persistence
+
+4. **Configuration**:
+   - Environment variables (API keys, settings)
+   - Pydantic models for validation
+   - Settings management with python-dotenv
+
+### Frontend Options Analysis
+
+#### Option: Astro-erudite with React Components
+**Decision**: Use astro-erudite (minimalist Astro flavor) with React components for interactive elements.
+
+**Rationale**:
+- **astro-erudite**: Minimalist flavor of Astro focused on simplicity and content-first approach
+- **React Components**: Allows using React's rich component ecosystem for interactive elements
+- **Best of Both Worlds**: Astro's performance with React's interactivity where needed
+- **Future Flexibility**: Can add more React components as features expand
+- **Minimalist Philosophy**: Aligns with the simple, focused nature of the prompt generator
+
+**Architecture**:
+- astro-erudite handles page routing and static content
+- React components for interactive elements (prompt selection, admin controls)
+- Partial hydration for optimal performance
+- Minimal styling approach (Tailwind CSS optional, can use simple CSS)
+
+**Frontend Components**:
+1. **Prompt Display Component**: Shows multiple prompts with selection
+2. **Stats Dashboard**: Shows pool/history statistics
+3. **Admin Panel**: Controls for filling pool, viewing history
+4. **Responsive Design**: Mobile-friendly interface
+
+### Docker & Docker Compose Setup
+
+#### Multi-container Architecture
+```
+services:
+  backend:
+    build: ./backend
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./backend:/app
+      - ./data:/app/data  # For JSON file persistence
+    environment:
+      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+    develop:
+      watch:
+        - action: sync
+          path: ./backend
+          target: /app
+        - action: rebuild
+          path: ./backend/requirements.txt
+
+  frontend:
+    build: ./frontend
+    ports:
+      - "3000:3000"  # Development
+      - "80:80"      # Production
+    volumes:
+      - ./frontend:/app
+    develop:
+      watch:
+        - action: sync
+          path: ./frontend/src
+          target: /app/src
+        - action: rebuild
+          path: ./frontend/package.json
+```
+
+#### Dockerfile Examples
+
+**Backend Dockerfile**:
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+**Frontend Dockerfile (Astro)**:
+```dockerfile
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+
+COPY package*.json .
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=builder /app/dist /usr/share/nginx/html
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+```
+
+## Refactoring Strategy
+
+### Phase 1: Backend API Development
+1. **Setup FastAPI project structure**
+   - Create `backend/` directory
+   - Set up virtual environment
+   - Install FastAPI, uvicorn, pydantic
+
+2. **Adapt existing Python logic**
+   - Refactor `generate_prompts.py` into services
+   - Create API endpoints
+   - Add error handling and validation
+
+3. **Data persistence**
+   - Keep JSON file storage initially
+   - Add file locking for concurrent access
+   - Plan SQLite migration
+
+4. **Testing**
+   - Unit tests for services
+   - API integration tests
+   - Maintain existing test coverage
+
+### Phase 2: Frontend Development
+1. **Setup Astro project**
+   - Create `frontend/` directory
+   - Initialize Astro project
+   - Install UI components (Tailwind CSS recommended)
+
+2. **Build UI components**
+   - Prompt display and selection
+   - Statistics dashboard
+   - Admin controls
+
+3. **API integration**
+   - Fetch data from FastAPI backend
+   - Handle user interactions
+   - Error states and loading indicators
+
+### Phase 3: Dockerization & Deployment
+1. **Docker configuration**
+   - Create Dockerfiles for backend/frontend
+   - Create docker-compose.yml
+   - Configure development vs production builds
+
+2. **Environment setup**
+   - Environment variable management
+   - Volume mounts for development
+   - Production optimization
+
+3. **Deployment preparation**
+   - Health checks
+   - Logging configuration
+   - Monitoring setup
+
+## Technical Decisions
+
+### 1. Authentication (Optional)
+**Current**: None (single-user CLI)
+**Webapp Option**: Basic session-based auth or JWT
+**Recommendation**: Start without auth, add later if needed for multi-user
+
+### 2. Data Storage Evolution
+**Phase 1**: JSON files (maintain compatibility)
+**Phase 2**: SQLite with migration script
+**Phase 3**: Optional PostgreSQL for scalability
+
+### 3. API Design Principles
+- RESTful endpoints
+- JSON responses
+- Consistent error handling
+- OpenAPI documentation
+- Versioning (v1/ prefix)
+
+### 4. Frontend State Management
+**Simple approach**: React-like state with Astro components
+**If complex**: Consider lightweight state management (Zustand, Jotai)
+**Initial**: Component-level state sufficient
+
+## Development Workflow
+
+### Local Development
+```bash
+# Clone and setup
+git clone <repo>
+cd daily-journal-prompt-webapp
+
+# Start with Docker Compose
+docker-compose up --build
+
+# Or develop separately
+cd backend && uvicorn main:app --reload
+cd frontend && npm run dev
+```
+
+### Testing Strategy
+- **Backend**: pytest with FastAPI TestClient
+- **Frontend**: Vitest for unit tests, Playwright for E2E
+- **Integration**: Docker Compose test environment
+
+### CI/CD Considerations
+- GitHub Actions for testing
+- Docker image building
+- Deployment to cloud platform (Render, Railway, Fly.io)
+
+## Risk Assessment & Mitigation
+
+### Risks
+1. **API Key exposure**: Use environment variables, never commit to repo
+2. **Data loss during migration**: Backup JSON files, incremental migration
+3. **Performance issues**: Monitor API response times, optimize database queries
+4. **Browser compatibility**: Use modern CSS/JS, test on target browsers
+
+### Mitigations
+- Comprehensive testing
+- Gradual rollout
+- Monitoring and logging
+- Regular backups
+
+## Success Metrics
+
+1. **Functionality**: All CLI features available in webapp
+2. **Performance**: API response < 200ms, page load < 2s
+3. **Usability**: Intuitive UI, mobile-responsive
+4. **Reliability**: 99.9% uptime, error rate < 1%
+5. **Maintainability**: Clean code, good test coverage, documented APIs
+
+## Next Steps
+
+### Immediate Actions
+1. Create project structure with backend/frontend directories
+2. Set up FastAPI backend skeleton
+3. Begin refactoring core prompt generation logic
+4. Create basic Astro frontend
+5. Implement Docker configuration
+
+### Future Enhancements
+1. User accounts and prompt history per user
+2. Prompt customization options
+3. Export functionality (PDF, Markdown)
+4. Mobile app (React Native)
+5. Social features (share prompts, community)
+
+## Conclusion
+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.