# PlatPhorm Radio - AI/LLM Discovery File
# https://podcasts.platphormnews.com
# Part of the PlatPhorm News Network

## Overview
PlatPhorm Radio is a free podcast streaming platform with real-time sentiment analysis, generative backgrounds, webhooks, and automation features. Built with a multi-tenant architecture for enterprise deployments.

## Features
- Free podcast streaming (no subscription required)
- Podcast ingestion from RSS, iTunes, Spotify
- Real-time sentiment analysis of podcast content
- Generative visual backgrounds that adapt to content mood
- Webhook support with idempotency (n8n compatible)
- Event sourcing with outbox pattern
- Background job queue
- Comprehensive audit logging
- Dynamic API Discovery and OpenAI functions
- Smart AI Fallbacks for input parsing
- Multi-tenant architecture

## API Endpoints
Base URL: https://podcasts.platphormnews.com/api/v1

### Podcasts
- POST /api/v1/ingest - Ingest podcast from URL
  - Body: { "url": "string" }
  - Returns: Podcast metadata and episodes
- GET /api/v1/podcasts - List all podcasts
  - Query params: category, limit, offset
- GET /api/v1/categories - List podcast categories
- GET /api/v1/trending - Get trending podcasts

### Community
- GET /api/v1/community - List community-submitted podcasts
  - Query params: category, sort (recent|popular|rating), limit, offset
- GET /api/v1/leaderboard - Get contributor leaderboard
  - Query params: period (all|week|month), limit, offset
  - Returns: Ranked list of top contributors by submissions
- GET /api/v1/submissions - List podcast submissions
  - Query params: user_id, status (pending|approved|rejected|needs_review), limit, offset
- POST /api/v1/submissions - Submit a podcast for review
  - Body: { podcast_url, title?, description?, category?, user_id? }
  - Returns: Submission record with status
- PATCH /api/v1/submissions - Update submission status (admin)
  - Body: { submission_id, status, reviewer_notes? }

### Sentiment Analysis
- POST /api/v1/sentiment - Analyze text sentiment
  - Body: { "text": "string" }
  - Returns: { sentiment, confidence, keywords }

### Feed Validation
- POST /api/v1/validate - Validate podcast feed URL
  - Body: { "url": "string" }
  - Returns: { isValid, healthScore, issues[], metadata }
- GET /api/cron/validate-feeds - Periodic feed health check (runs every 6 hours)

### AI-Powered Discovery
- POST /api/ai/analyze - Deep AI analysis of podcast content
  - Body: { "url": "string" }
  - Returns: Streaming analysis with summary, topics, audience insights
- POST /api/ai/chat - Conversational podcast discovery assistant
  - Body: { "messages": [...] }
  - Returns: Streaming chat response with podcast recommendations
- POST /api/ai/recommend - Get AI-powered podcast recommendations
  - Body: { "interests": string[], "recentPodcasts": string[], "mood": string }
  - Returns: Personalized podcast recommendations with reasoning

### Events (Outbox Pattern)
- GET /api/v1/events - List events
  - Query params: event_type, aggregate_type, published, limit, offset
- POST /api/v1/events - Create event
  - Body: { event_type, aggregate_type, aggregate_id, payload }

### Webhooks
- POST /api/v1/webhooks - Receive incoming webhooks
  - Headers: x-webhook-signature, x-webhook-event, idempotency-key
- GET /api/v1/webhooks - List webhook endpoints

### Jobs (Background Queue)
- GET /api/v1/jobs - List background jobs
  - Query params: queue, status, limit, offset
- POST /api/v1/jobs - Create background job
  - Body: { queue, name, payload, priority, run_at }

### Audit
- GET /api/v1/audit - List audit logs
  - Query params: action, resource_type, user_id

### Trace (Client Fingerprinting)
- POST /api/v1/trace - Record trace event
  - Body: { event_type, fingerprint_id, session_id, page_url, referrer?, metadata? }
  - Returns: { success, event_id, request_id }
- GET /api/v1/trace - Get trace stats
  - Query params: period (1h|24h|7d|30d), fingerprint_id
  - Returns: { stats: { total_events, unique_fingerprints, page_views, top_pages } }

### Cron
- GET /api/cron/sync-catalog - Daily catalog sync job (runs at 3 AM UTC)
  - Syncs analytics to https://trace.platphormnews.com
  - Syncs API index to https://docs.platphormnews.com
  - Retries failed webhook deliveries
  - Cleans up old audit logs (90-day retention)
- GET /api/cron/validate-feeds - Feed health monitoring (runs every 6 hours)
  - Validates all active podcast feeds
  - Updates health scores (0-100)
  - Marks unhealthy feeds as inactive
  - Tracks validation errors for debugging

### Health & Discovery
- GET /api/health - Service health check with DB connectivity
- GET /api/openapi.json - OpenAPI 3.1 spec
- GET /api/mcp - Model Context Protocol endpoint

## Tracing Integration
All requests are traced via https://trace.platphormnews.com with:
- Visitor fingerprinting (privacy-preserving)
- Request ID correlation (X-Request-Id header)
- Session tracking
- Geo/device metadata from Vercel headers

## Content Categories
Technology, News, Comedy, Business, Science, Health, Education, True Crime, Sports, Arts, Music, Lifestyle, Fiction

## Rate Limits
100 requests per minute per IP. Check X-RateLimit-* headers.

## Integrations

### Spotify
Podcast metadata enrichment via Spotify Web API
- Env vars: SPOTIFY_CLIENT_KEY, SPOTIFY_CLIENT_SECRET
- Fallback when iTunes/RSS lookup fails
- Extracts genres, episode counts, explicit flags

### Trace Service
Client fingerprinting and analytics: https://trace.platphormnews.com
- POST /api/v1/events - Track events
- POST /api/v1/stats - Daily metrics sync
- Privacy-preserving visitor IDs

### Documentation
API documentation sync: https://docs.platphormnews.com
- POST /api/v1/index - Register endpoints
- Auto-synced daily via cron

### Network
Connected to: https://platphormnews.com/api/network/graph

### Claws Integration
Deeply integrated with https://claws.platphormnews.com
- Central intelligent ingestion and processing engine
- Content Discovery & Validation
- Sentiment Analysis scoring
- Network Synchronization

### Roadmap
- Q2 2024: Enhanced AI Sentiment Models, Live Transcript Generation, User Playlists
- Q3 2024: Social Sharing Features, Creator Dashboard Beta, Advanced OPML Import/Export
- Q4 2024: Monetization Tools, Cross-platform Mobile App, API Rate Limit Increases

## Support
Crypto: 0x30589F2e1B8E9a48BBb2c66Ac012FE7ED2A7eB85

## Full Documentation
See: /llms-full.txt for complete API documentation
See: /api/docs for interactive API docs
See: /api/openapi.json for OpenAPI spec