# 🔥 Fractafrag

**A self-hosted GLSL shader platform — browse, create, generate, and share real-time GPU visuals.**

Fractafrag fuses three experiences:
- **TikTok-style adaptive feed** of living, animated shaders that learns your taste
- **Shadertoy-style code editor** for writing, forking, and publishing GLSL shaders
- **AI generation layer** where you describe what you want and the platform writes the shader

Plus a **desire queue / bounty board** where users express what they want to see, and human creators or AI agents fulfill those requests.

## Quick Start

```bash
# 1. Clone and configure
cp .env.example .env
# Edit .env with your secrets

# 2. Launch everything
docker compose up -d

# 3. Open
open http://localhost
```

## Architecture

```
nginx (reverse proxy)
├── /         → React frontend (Vite)
├── /api/*    → FastAPI backend
└── /mcp/*    → MCP server (AI agent interface)

postgres (pgvector/pgvector:pg16) — primary datastore + vector similarity
redis (redis:7-alpine) — cache, rate limiting, job queue
renderer — headless Chromium shader renderer
worker — Celery job processor (render, embed, AI generate)
```

## Tech Stack

| Layer | Tech |
|-------|------|
| Frontend | React 18, Vite, Three.js, TanStack Query, Zustand, Tailwind CSS |
| Backend | Python, FastAPI, SQLAlchemy, Pydantic |
| Database | PostgreSQL 16 + pgvector, Redis 7 |
| Jobs | Celery + Redis |
| Renderer | Node.js + Puppeteer (Headless Chromium) |
| MCP | Python MCP SDK, HTTP+SSE transport |
| Payments | Stripe (subscriptions + Connect) |
| Container | Docker Compose, single-stack |

## Milestone Roadmap

| Milestone | Focus | Status |
|-----------|-------|--------|
| **M0** | Infrastructure + Auth | 🚧 In Progress |
| **M1** | Core Shader Loop (editor, submit, feed) | ⏳ |
| **M2** | Intelligence Layer (MCP, recommendations) | ⏳ |
| **M3** | Desire Economy (bounties, fulfillment) | ⏳ |
| **M4** | Monetization (Stripe, subscriptions) | ⏳ |
| **M5** | AI Generation (prompt → shader) | ⏳ |

## Development

```bash
# API direct access (dev mode)
http://localhost:8000/api/docs   # Swagger UI
http://localhost:8000/health     # Health check

# Services
http://localhost:5173   # Vite dev server
http://localhost:3200   # MCP server
http://localhost:3100   # Renderer
```

## License

Private — see DECISIONS.md for project governance.