bulk commit changes!

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

@@ -0,0 +1,82 @@
+## 1. Project Setup
+
+- [x] 1.1 Create project directory structure (backend/, frontend/, docker/)
+- [x] 1.2 Initialize Python project with pyproject.toml (FastAPI, SQLAlchemy, APScheduler, httpx)
+- [x] 1.3 Create requirements.txt for Docker build
+- [x] 1.4 Set up Tailwind CSS configuration
+- [x] 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
+
+- [x] 2.1 Create SQLAlchemy models (NewsItem with fields: id, headline, summary, source_url, image_url, image_credit, published_at, created_at, archived)
+- [x] 2.2 Create database initialization and migration scripts
+- [x] 2.3 Implement database connection management with SQLite
+- [x] 2.4 Create repository functions (create_news, get_recent_news, get_news_paginated, archive_old_news, delete_archived_news)
+
+## 3. News Aggregation Service
+
+- [x] 3.1 Implement Perplexity API client with httpx and cost logging
+- [x] 3.2 Create news fetch function with query "latest AI news"
+- [x] 3.3 Implement exponential backoff retry logic (3 attempts)
+- [x] 3.4 Add duplicate detection (headline match within 24h)
+- [x] 3.5 Create hourly scheduled job with APScheduler
+- [x] 3.6 Implement image URL fetching from Perplexity
+- [x] 3.7 Add image download and optimization with Pillow (configurable quality)
+- [x] 3.8 Implement OpenRouter API fallback for news fetching
+- [x] 3.9 Add default placeholder image fallback
+
+## 4. Backend API
+
+- [x] 4.1 Create FastAPI application structure
+- [x] 4.2 Implement GET /api/news endpoint with pagination (cursor-based)
+- [x] 4.3 Implement GET /api/news/latest endpoint for hero block
+- [x] 4.4 Add CORS middleware for frontend access
+- [x] 4.5 Create Pydantic schemas for API responses
+- [x] 4.6 Implement health check endpoint
+- [x] 4.7 Add API error handling and logging
+
+## 5. Frontend Implementation
+
+- [x] 5.1 Create HTML structure with ClawFort branding
+- [x] 5.2 Implement hero block with Alpine.js (latest news display)
+- [x] 5.3 Create news feed component with Alpine.js
+- [x] 5.4 Implement infinite scroll with Intersection Observer API
+- [x] 5.5 Add loading indicators and "No more news" message
+- [x] 5.6 Implement source attribution display
+- [x] 5.7 Add image lazy loading
+- [x] 5.8 Style with Tailwind CSS (responsive design)
+- [x] 5.9 Add "Powered by Perplexity" footer attribution
+- [x] 5.10 Implement Umami analytics integration (conditional on env vars)
+- [x] 5.11 Add analytics events: page view, scroll depth (25/50/75/100%), CTA clicks
+
+## 6. Archive Management
+
+- [x] 6.1 Implement nightly cleanup job (archive >30 days)
+- [x] 6.2 Create permanent deletion job (>60 days archived)
+- [x] 6.3 Add retention configuration (default 30 days)
+
+## 7. Docker Containerization
+
+- [x] 7.1 Create Dockerfile with multi-stage build (Python + static assets)
+- [x] 7.2 Create docker-compose.yml for local development
+- [x] 7.3 Add volume mount for SQLite persistence
+- [x] 7.4 Configure environment variable handling
+- [x] 7.5 Optimize image size (slim Python base)
+- [x] 7.6 Add .dockerignore file
+
+## 8. Testing & Validation
+
+- [x] 8.1 Test Perplexity API integration manually
+- [x] 8.2 Verify hourly news fetching works
+- [x] 8.3 Test infinite scroll pagination
+- [x] 8.4 Verify responsive design on mobile/desktop
+- [x] 8.5 Test container build and run
+- [x] 8.6 Verify data persistence across container restarts
+- [x] 8.7 Test archive cleanup functionality
+
+## 9. Documentation
+
+- [x] 9.1 Create README.md with setup instructions
+- [x] 9.2 Document environment variables
+- [x] 9.3 Add deployment instructions
+- [x] 9.4 Document API endpoints