# Platphorm Decks - AI/LLM Discovery File
# For AI models, assistants, and language model applications
# Last Updated: 2026-03-23
# Version: 0.0.1

## Service Overview

**Name:** Platphorm Decks
**Description:** Cinematic presentation slides and visual content platform for the PlatPhorm Network
**URL:** https://decks.platphormnews.com
**Status:** Production
**Availability:** 99.9% SLA

## Core APIs

### 1. Health Check
- **Endpoint:** GET /api/health
- **Purpose:** Service status and monitoring
- **Response:** JSON with status, version, uptime
- **Rate Limit:** 1000 req/min
- **Cache:** no-cache
- **Authentication:** None

### 2. API Documentation
- **Endpoint:** GET /api/docs
- **Purpose:** Full OpenAPI 3.1.0 specification
- **Format:** application/json
- **Response Time:** < 100ms
- **Rate Limit:** 100 req/min (spec requests)
- **Documentation:** https://docs.platphormnews.com/decks

### 3. Network Discovery
- **Endpoint:** GET /api/v1/network
- **Purpose:** PlatPhorm network sites, verticals, and metadata
- **Response Fields:** id, name, domain, url, status, vertical, mcpEnabled
- **Data:** ~20 network sites with real-time status
- **Cache:** 5 minutes (s-maxage=300)
- **Rate Limit:** 500 req/min

### 4. Slides Configuration
- **Endpoint:** GET /api/slides
- **Purpose:** Current presentation slides with full metadata
- **Response:** Array of slide objects with styling, animations, content
- **Fields:** title, description, network data, styles, CTA
- **Cache:** 1 hour
- **Rate Limit:** 1000 req/min

### 5. Content Feed
- **Endpoint:** GET /rss.xml
- **Format:** RSS 2.0 with Atom extensions
- **Update Frequency:** Weekly
- **Items:** Announcements, releases, updates

- **Endpoint:** GET /feed.xml
- **Format:** Atom 1.0
- **Update Frequency:** Weekly

### 6. Sitemaps
- **Endpoint:** GET /sitemap.xml
- **Format:** XML sitemap protocol
- **Contains:** All public URLs with lastmod and priority
- **Cache:** 24 hours

- **Endpoint:** GET /robots.txt
- **Format:** Robots.txt protocol
- **Directives:** Allow/Disallow rules, sitemaps, crawl-delay

## Data Schema

### NetworkSite Object
```json
{
  "id": "string",
  "name": "string",
  "domain": "string",
  "url": "string",
  "favicon": "string (URL)",
  "status": "active|maintenance|offline",
  "vertical": "string (infrastructure|security|devtools|ai|content)",
  "mcpEnabled": "boolean",
  "description": "string",
  "lastChecked": "ISO8601 timestamp"
}
```

### Slide Object
```json
{
  "id": "string",
  "type": "string (hero|masked-text|narrative|announcement|character)",
  "title": "string",
  "subtitle": "string",
  "description": "string or string[]",
  "network": { /* NetworkSite object */ },
  "style": {
    "accentColor": "oklch() or hex",
    "backgroundColor": "oklch() or hex"
  },
  "cta": {
    "text": "string",
    "href": "string"
  },
  "media": {
    "type": "image|video",
    "src": "string (URL)",
    "alt": "string"
  }
}
```

## Authentication & Security

- **Default Access:** Public, trusted domain (*.platphormnews.com)
- **No Authentication:** Required for read-only public endpoints
- **API Keys:** Available for enhanced rate limits
- **HTTPS:** Required for all endpoints
- **CORS:** Enabled for *.platphormnews.com domains
- **Security Headers:** HSTS, X-Content-Type-Options, X-Frame-Options

## Rate Limiting

- **Default:** 1000 requests per minute per IP
- **Headers Provided:**
  - X-RateLimit-Limit: Total limit
  - X-RateLimit-Remaining: Requests left
  - X-RateLimit-Reset: Unix timestamp
- **Premium:** Custom limits available (contact api@platphormnews.com)
- **Burst:** Up to 2x rate for 10 seconds

## Performance Metrics

- **Response Time (p50):** < 50ms
- **Response Time (p95):** < 200ms
- **Response Time (p99):** < 1000ms
- **Uptime:** 99.9% (excludes maintenance windows)
- **Availability:** 24/7/365

## Error Handling

**HTTP Status Codes:**
- 200: Success
- 400: Bad Request (invalid parameters)
- 401: Unauthorized (missing/invalid auth)
- 404: Not Found (resource doesn't exist)
- 429: Rate Limited (too many requests)
- 500: Server Error (internal error)
- 503: Service Unavailable (maintenance)

**Error Response Format:**
```json
{
  "error": "error_code",
  "message": "human-readable description",
  "details": { /* error details */ }
}
```

## Caching Strategy

- **Browser Cache:** max-age varies by endpoint
- **CDN Cache:** s-maxage specified per endpoint
- **Stale-While-Revalidate:** Enabled for better UX
- **Cache Busting:** Via version headers and ETags
- **Invalidation:** Automatic on content updates

## Content Types & Verticals

**Network Verticals:**
- infrastructure - Core network services
- security - Security and compliance tools
- devtools - Developer tools and utilities
- ai - Artificial intelligence services
- content - Content and publishing

**Slide Types:**
- hero - Full-screen introductions
- masked-text - Animated text reveals
- narrative - Story-driven slides
- announcement - Important news
- character - Character/persona showcase

## Integration Points

### OpenAPI Compliance
- Full OpenAPI 3.1.0 specification available
- JSON Schema validation
- Request/response schemas documented
- Server URLs for all environments

### Webhook Support
- Event types: network.update, slide.publish, status.change
- Delivery: HTTPS POST with HMAC-SHA256 signature
- Retry: Exponential backoff (5 attempts)
- Idempotency: Via X-Idempotency-Key header

### Related Services
- Docs: https://docs.platphormnews.com
- Network Hub: https://platphormnews.com
- Monitor: https://monitor.platphormnews.com
- API Gateway: https://api.platphormnews.com
- MCP Hub: https://mcp.platphormnews.com

## Support & Resources

**Documentation:**
- Full Docs: https://docs.platphormnews.com/decks
- API Reference: https://docs.platphormnews.com/decks/api
- Guides: https://docs.platphormnews.com/decks/guides
- Examples: https://github.com/mbarbine/platphorm-decks

**Status & Support:**
- API Status: https://status.platphormnews.com
- Support Email: api@platphormnews.com
- GitHub Issues: https://github.com/mbarbine/platphorm-decks/issues
- Community: https://platphormnews.com

## Technology Stack

- **Frontend:** React 19, Next.js 16, TypeScript
- **Animations:** Framer Motion, CSS transitions
- **Styling:** Tailwind CSS, CSS-in-JS
- **Animation:** Hardware-accelerated scroll-linked animations
- **Deployment:** Vercel Edge Network
- **Database:** PostgreSQL (Supabase)
- **Caching:** Redis, CDN

## Compliance & Standards

- **Accessibility:** WCAG 2.1 Level AA
- **Performance:** Core Web Vitals optimized
- **Security:** OWASP Top 10 mitigated
- **SEO:** JSON-LD, Open Graph, Twitter Cards
- **Standards:** HTML5, ES2024, REST

## Usage Examples

### Get Network Status
```bash
curl https://decks.platphormnews.com/api/v1/network
```

### Check Service Health
```bash
curl https://decks.platphormnews.com/api/health
```

### Fetch OpenAPI Spec
```bash
curl https://decks.platphormnews.com/api/docs
```

### Get Slides
```bash
curl https://decks.platphormnews.com/api/slides
```

## License

MIT License - See https://github.com/mbarbine/platphorm-decks/blob/main/LICENSE

## Changelog

**v0.0.1** - Initial release
- Core slides engine
- Network integration
- API endpoints
- Documentation