daily-journal-prompt/AGENTS.md

# 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.