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

Context

ClawFort needs a stunning one-page placeholder website that automatically aggregates and displays AI news hourly. The site must be containerized, use Perplexity API for news generation, and feature infinite scroll with 30-day retention.

Current State: Greenfield project - no existing codebase.

Constraints:

• Must use Perplexity API (API key via environment variable)
• Containerized deployment (Docker)
• Lean JavaScript framework for frontend
• 30-day news retention with archiving
• Hourly automated updates

Goals / Non-Goals

Goals:

• Stunning one-page website with ClawFort branding
• Hourly AI news aggregation via Perplexity API
• Dynamic hero block with featured news and image
• Infinite scroll news feed (10 initial items)
• 30-day retention with automatic archiving
• Source attribution for news and images
• Fully containerized deployment
• Responsive design

Non-Goals:

• User authentication/accounts
• Manual news curation interface
• Real-time updates (polling only)
• Multi-language support
• CMS integration
• SEO optimization beyond basic meta tags

Decisions

Architecture: Monolithic Container

Decision: Single container with frontend + backend + SQLite Rationale: Simplicity for a placeholder site, easy deployment, no external database dependencies Alternative: Microservices with separate DB container - rejected as overkill for this scope

Frontend Framework: Alpine.js + Tailwind CSS

Decision: Alpine.js for lean reactivity, Tailwind for styling Rationale: Minimal bundle size (~15kb), no build step complexity, perfect for one-page sites Alternative: React/Vue - rejected as too heavy for simple infinite scroll and hero display

Backend: Python (FastAPI) + APScheduler

Decision: FastAPI for REST API, APScheduler for cron-like jobs Rationale: Fast to develop, excellent async support, built-in OpenAPI docs, simple scheduling Alternative: Node.js/Express - rejected; Python better for data processing and Perplexity integration

Database: SQLite with SQLAlchemy

Decision: SQLite for zero-config persistence Rationale: No separate DB container needed, sufficient for 30-day news retention (~1000-2000 records) Alternative: PostgreSQL - rejected as adds deployment complexity

News Aggregation Strategy

Decision: Hourly cron job queries Perplexity for "latest AI news" with image generation Rationale: Simple, reliable, cost-effective Implementation:

• Perplexity API call: "What are the latest AI news from the last hour?"
• Store: headline, summary, source URL, image URL, timestamp
• Attribution: Display source name and image credit

Image Strategy

Decision: Use Perplexity to suggest relevant images or generate via DALL-E if available, with local image optimization Rationale: Consistent with AI theme, no copyright concerns, plus configurable compression Implementation:

• Download and optimize images locally using Pillow
• Configurable quality setting via IMAGE_QUALITY env var (1-100, default 85)
• Store optimized images in /app/static/images/
• Serve optimized versions, fallback to original URL if optimization fails Alternative: Unsplash API - rejected to keep dependencies minimal

Infinite Scroll Implementation

Decision: Cursor-based pagination with Intersection Observer API Rationale: Efficient for large datasets, simple Alpine.js integration Page Size: 10 items per request

Archive Strategy

Decision: Soft delete (archived flag) + nightly cleanup job Rationale: Easy to implement, data recoverable if needed Cleanup: Move items >30 days to archive table or delete

Risks / Trade-offs

[Risk] Perplexity API rate limits or downtime → Mitigation: Implement exponential backoff, cache last successful fetch, display cached content with "last updated" timestamp, fallback to OpenRouter API if configured

[Risk] Container storage grows unbounded → Mitigation: SQLite WAL mode, volume mounts for persistence, 30-day hard limit on retention

[Risk] News quality varies → Mitigation: Basic filtering (require title + summary), manual blacklist capability in config

[Risk] Cold start performance → Mitigation: SQLite connection pooling, frontend CDN-ready static assets

[Trade-off] SQLite vs PostgreSQL → SQLite limits concurrent writes but acceptable for read-heavy news site

[Trade-off] Single container vs microservices → Easier deployment but less scalable; acceptable for placeholder site

Migration Plan

1. Development: Local Docker Compose setup
2. Environment: Configure PERPLEXITY_API_KEY in .env
3. Build: docker build -t clawfort-site .
4. Run: docker run -e PERPLEXITY_API_KEY=xxx -p 8000:8000 clawfort-site
5. Data: SQLite volume mount for persistence across restarts

Open Questions (Resolved)

1. Admin panel? → Deferred to future
2. Image optimization? → Yes, local optimization with Pillow, configurable quality via IMAGE_QUALITY env var
3. Analytics? → Umami integration with UMAMI_SCRIPT_URL and UMAMI_WEBSITE_ID env vars, track page views, scroll events, and CTA clicks
4. API cost monitoring? → Log Perplexity usage, fallback to OpenRouter API if OPENROUTER_API_KEY configured