112 lines
5.2 KiB
Markdown
112 lines
5.2 KiB
Markdown
## 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
|