From 9c64cb0c2fb0c28b372fee35efe704ce8bc03617 Mon Sep 17 00:00:00 2001 From: finn Date: Sat, 3 Jan 2026 04:00:52 -0700 Subject: [PATCH] planning checkpoint next step in agents --- AGENTS.md | 301 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 300 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 0a9d82e..106177d 100644 --- a/AGENTS.md +++ b/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 +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.