finn/daily-journal-prompt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9c64cb0c2fb0c28b372fee35efe704ce8bc03617
daily-journal-prompt/AGENTS.md

9.3 KiB
Raw Blame History

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:

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):

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

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

Reference in New Issue View Git Blame Copy Permalink