clawfort/openspec/changes/archive/2026-02-13-p01-robust-onepager/tasks.md

1. Project Setup

• 1.1 Create project directory structure (backend/, frontend/, docker/)
• 1.2 Initialize Python project with pyproject.toml (FastAPI, SQLAlchemy, APScheduler, httpx)
• 1.3 Create requirements.txt for Docker build
• 1.4 Set up Tailwind CSS configuration
• 1.5 Create .env.example with all environment variables (PERPLEXITY_API_KEY, IMAGE_QUALITY, OPENROUTER_API_KEY, UMAMI_SCRIPT_URL, UMAMI_WEBSITE_ID)

2. Database Layer

• 2.1 Create SQLAlchemy models (NewsItem with fields: id, headline, summary, source_url, image_url, image_credit, published_at, created_at, archived)
• 2.2 Create database initialization and migration scripts
• 2.3 Implement database connection management with SQLite
• 2.4 Create repository functions (create_news, get_recent_news, get_news_paginated, archive_old_news, delete_archived_news)

3. News Aggregation Service

• 3.1 Implement Perplexity API client with httpx and cost logging
• 3.2 Create news fetch function with query "latest AI news"
• 3.3 Implement exponential backoff retry logic (3 attempts)
• 3.4 Add duplicate detection (headline match within 24h)
• 3.5 Create hourly scheduled job with APScheduler
• 3.6 Implement image URL fetching from Perplexity
• 3.7 Add image download and optimization with Pillow (configurable quality)
• 3.8 Implement OpenRouter API fallback for news fetching
• 3.9 Add default placeholder image fallback

4. Backend API

• 4.1 Create FastAPI application structure
• 4.2 Implement GET /api/news endpoint with pagination (cursor-based)
• 4.3 Implement GET /api/news/latest endpoint for hero block
• 4.4 Add CORS middleware for frontend access
• 4.5 Create Pydantic schemas for API responses
• 4.6 Implement health check endpoint
• 4.7 Add API error handling and logging

5. Frontend Implementation

• 5.1 Create HTML structure with ClawFort branding
• 5.2 Implement hero block with Alpine.js (latest news display)
• 5.3 Create news feed component with Alpine.js
• 5.4 Implement infinite scroll with Intersection Observer API
• 5.5 Add loading indicators and "No more news" message
• 5.6 Implement source attribution display
• 5.7 Add image lazy loading
• 5.8 Style with Tailwind CSS (responsive design)
• 5.9 Add "Powered by Perplexity" footer attribution
• 5.10 Implement Umami analytics integration (conditional on env vars)
• 5.11 Add analytics events: page view, scroll depth (25/50/75/100%), CTA clicks

6. Archive Management

• 6.1 Implement nightly cleanup job (archive >30 days)
• 6.2 Create permanent deletion job (>60 days archived)
• 6.3 Add retention configuration (default 30 days)

7. Docker Containerization

• 7.1 Create Dockerfile with multi-stage build (Python + static assets)
• 7.2 Create docker-compose.yml for local development
• 7.3 Add volume mount for SQLite persistence
• 7.4 Configure environment variable handling
• 7.5 Optimize image size (slim Python base)
• 7.6 Add .dockerignore file

8. Testing & Validation

• 8.1 Test Perplexity API integration manually
• 8.2 Verify hourly news fetching works
• 8.3 Test infinite scroll pagination
• 8.4 Verify responsive design on mobile/desktop
• 8.5 Test container build and run
• 8.6 Verify data persistence across container restarts
• 8.7 Test archive cleanup functionality

9. Documentation

• 9.1 Create README.md with setup instructions
• 9.2 Document environment variables
• 9.3 Add deployment instructions
• 9.4 Document API endpoints